ai-control-center 1.15.2

package/lib/actions/deploy.js

@@ -0,0 +1,1229 @@
+import inquirer from 'inquirer';
+import { spawn } from 'child_process';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from 'fs';
+import { resolve } from 'path';
+import chalk from 'chalk';
+import { capture, isAvailable, runCopilot, runGemini } from '../utils/runner.js';
+import { getWorkflowDir, getRootDir, getStatus, updateStatus } from '../utils/pipeline.js';
+import { printError, printDeployErrorPanel } from '../utils/display.js';
+import { logActivity, logRawBlock, printActivityHeader, printActivityFooter } from '../utils/activity-log.js';
+import { celebrate } from '../utils/notify.js';
+import { spinner, spinCycle } from '../utils/spinner.js';
+
+const MAX_ATTEMPTS = 3;
+
+// ─── Test level prompt ─────────────────────────────────────────────────────────
+// Returns the --test-level flag string to append to any sf deploy command.
+
+async function askTestLevel() {
+  const { level } = await inquirer.prompt([{
+    type:    'rawlist',
+    name:    'level',
+    message: 'Run test classes?',
+    prefix:  chalk.cyan('◆'),
+    choices: [
+      {
+        name:  `✓  Run Local Tests   ${chalk.dim('·')}  ${chalk.yellow('full validation')}  ${chalk.dim('(recommended before production)')}`,
+        value: 'RunLocalTests',
+      },
+      {
+        name:  `⚡  No Tests          ${chalk.dim('·')}  ${chalk.green('fast deploy')}      ${chalk.dim('(skip — good for config/LWC changes)')}`,
+        value: 'NoTestRun',
+      },
+      { name: chalk.dim('Back'), value: 'cancel' },
+    ],
+  }]);
+  return level === 'cancel' ? null : level;
+}
+
+// ─── Auto-countdown helper ─────────────────────────────────────────────────────
+// Prints "→  <message>  3s" and counts down.  Ctrl+C aborts the whole process
+// (which is fine — user deliberately interrupts).  Returns when done.
+
+async function autoCountdown(message, seconds = 3) {
+  const write = s => process.stdout.write(s);
+  write(`\n  ${chalk.dim('→')}  ${chalk.dim(message)}  ${chalk.cyan(`${seconds}s`)}`);
+  for (let i = seconds - 1; i >= 0; i--) {
+    await new Promise(r => setTimeout(r, 1000));
+    const label = i > 0 ? `${i}s` : 'starting...';
+    write(`\r  ${chalk.dim('→')}  ${chalk.dim(message)}  ${chalk.cyan(label)}      `);
+  }
+  write('\n\n');
+}
+
+// ─── Entry point ───────────────────────────────────────────────────────────────
+
+export async function deployAction() {
+  const { choice } = await inquirer.prompt([{
+    type:     'list',
+    name:     'choice',
+    message:  'Deploy options',
+    prefix:   chalk.cyan('◆'),
+    choices: [
+      {
+        name:  `◎  Smart Deploy   ${chalk.dim('·')}  ${chalk.green('changed files only')}  ${chalk.dim('(fast)')}`,
+        value: 'smart',
+      },
+      {
+        name:  `▸  Full Deploy    ${chalk.dim('·')}  ${chalk.yellow('all metadata')}        ${chalk.dim('(slow)')}`,
+        value: 'full',
+      },
+      new inquirer.Separator(chalk.dim('  ──────────────────────────────────────')),
+      {
+        name:  `◇  Dry Run        ${chalk.dim('·')}  changed files only  ${chalk.dim('(validate, no deploy)')}`,
+        value: 'dryrun-smart',
+      },
+      {
+        name:  `◇  Dry Run        ${chalk.dim('·')}  full metadata       ${chalk.dim('(validate, no deploy)')}`,
+        value: 'dryrun-full',
+      },
+      new inquirer.Separator(chalk.dim('  ──────────────────────────────────────')),
+      {
+        name:  '⊙  Deploy Specific Class  (enter name manually)',
+        value: 'specific',
+      },
+      {
+        name:  '≡  View Last Deploy Status',
+        value: 'status',
+      },
+      new inquirer.Separator(chalk.dim('  ──────────────────────────────────────')),
+      { name: chalk.dim('  Back'), value: 'back' },
+    ],
+  }]);
+
+  if (choice === 'back') return;
+
+  // ── Status ────────────────────────────────────────────────────────────────────
+  if (choice === 'status') {
+    printActivityHeader('PIPELINE — Last Deploy Status');
+    const stopCycle = spinCycle('Deploy', ['Fetching deploy report...'], 3000, 'yellow');
+    const result = await capture('sf project deploy report --json');
+    stopCycle(); spinner.stop();
+    showStatusReport(result);
+    return;
+  }
+
+  // ── Specific class ────────────────────────────────────────────────────────────
+  if (choice === 'specific') {
+    const { className } = await inquirer.prompt([{
+      type:     'input',
+      name:     'className',
+      message:  'Class name to deploy (e.g. UserService):',
+      validate: v => v.trim().length > 0 || 'Class name required',
+    }]);
+    const name      = className.trim();
+    const testLevel = await askTestLevel();
+    if (!testLevel) return;
+    printActivityHeader(`PIPELINE — Deploy ${name}`);
+    await runDeployWithOrchestration(
+      `sf project deploy start --metadata ApexClass:${name} --test-level ${testLevel}`,
+      `Deploying ApexClass:${name}`,
+      false, [{ type: 'ApexClass', name }]
+    );
+    return true;
+  }
+
+  // ── Smart deploy (changed files since last deploy) ────────────────────────────
+  if (choice === 'smart' || choice === 'dryrun-smart') {
+    const isDryRun = choice === 'dryrun-smart';
+    printActivityHeader(`PIPELINE — ${isDryRun ? 'Dry Run' : 'Smart Deploy'}  ·  Changed Since Last Deploy`);
+
+    logActivity('PIPELINE', 'Comparing HEAD against last deployed commit...');
+    const scan = await getChangedMetadata();
+
+    if (scan.components.length === 0) {
+      showEmptyDeployState(scan);
+      return;
+    }
+
+    const testLevel = await askTestLevel();
+    if (!testLevel) return;
+
+    // Show commit range + what will be deployed, then auto-proceed
+    showChangedComponents(scan, isDryRun);
+    await autoCountdown(
+      `${isDryRun ? 'Validating' : 'Deploying'} ${scan.components.length} component(s)  ·  Ctrl+C to cancel`
+    );
+
+    // Use --source-dir per changed component so SF CLI discovers all files itself.
+    // This is more reliable than --metadata because it never misses sub-types
+    // (fields inside an object dir, assets inside an LWC dir, etc.).
+    const sourceDirs = [...new Set(scan.components.map(c => c.sourceDir))];
+    const sourceFlags = sourceDirs.map(d => `--source-dir "${d}"`).join(' ');
+    const command = isDryRun
+      ? `sf project deploy start --dry-run ${sourceFlags} --test-level ${testLevel}`
+      : `sf project deploy start ${sourceFlags} --test-level ${testLevel}`;
+
+    await runDeployWithOrchestration(command, `Smart Deploy (${scan.components.length} components)`, isDryRun, scan.components);
+    return true;
+  }
+
+  // ── Full deploy ────────────────────────────────────────────────────────────────
+  if (choice === 'full' || choice === 'dryrun-full') {
+    const isDryRun = choice === 'dryrun-full';
+    printActivityHeader(`PIPELINE — ${isDryRun ? 'Dry Run' : 'Full Deploy'}  ·  All Metadata`);
+
+    const testLevel = await askTestLevel();
+    if (!testLevel) return;
+
+    const { confirmed } = await inquirer.prompt([{
+      type:    'confirm',
+      name:    'confirmed',
+      message: `${isDryRun ? 'Validate' : 'Deploy'} ALL metadata to default org? This can take 10–20 min.`,
+      prefix:  chalk.yellow('~'),
+      default: false,
+    }]);
+    if (!confirmed) { logActivity('PIPELINE', 'Cancelled.'); return; }
+
+    const command = isDryRun
+      ? `sf project deploy start --dry-run --test-level ${testLevel}`
+      : `sf project deploy start --test-level ${testLevel}`;
+
+    await runDeployWithOrchestration(command, 'Full Deploy', isDryRun, null);
+    return true;
+  }
+}
+
+// ─── Commit tracking ──────────────────────────────────────────────────────────
+
+function getLastDeployedCommit() {
+  return getStatus().last_deployed_commit || null;
+}
+
+async function saveDeployedCommit() {
+  const r = await capture('git rev-parse HEAD');
+  const hash = r.stdout.trim();
+  if (hash && hash.length === 40) {
+    updateStatus({ last_deployed_commit: hash });
+    logActivity('PIPELINE', `Deploy recorded at commit ${hash.slice(0, 8)}`, 'success');
+  }
+}
+
+// ─── Detect changed Salesforce files since last deploy ────────────────────────
+//
+// Returns:
+//   {
+//     components:       [{ ref, type, name }]  — deduplicated metadata refs
+//     commitInfo:       { base, head, commits: [{hash, message}], count, note }
+//     uncommittedCount: number                 — files not yet committed
+//   }
+
+async function getChangedMetadata() {
+  const root       = getRootDir();
+  const baseCommit = getLastDeployedCommit();
+
+  let committedFiles   = [];
+  let commitInfo       = null;
+  let uncommittedFiles = [];
+
+  // ── Always include uncommitted/untracked changes too ─────────────────────────
+  const statusResult = await capture('git status --porcelain -- force-app/', [], { cwd: root });
+  uncommittedFiles = statusResult.stdout
+    .split('\n').filter(Boolean)
+    .map(l => l.slice(3).trim())
+    .filter(f => f.startsWith('force-app/'));
+
+  // ── Committed changes since last deploy ──────────────────────────────────────
+  const headResult = await capture('git rev-parse HEAD', [], { cwd: root });
+  const headHash   = headResult.stdout.trim();
+
+  if (baseCommit) {
+    // Verify the stored commit still exists (handles rebases)
+    const check = await capture(`git cat-file -t ${baseCommit}`, [], { cwd: root });
+
+    if (check.code !== 0) {
+      logActivity('PIPELINE', `Stored commit ${baseCommit.slice(0, 8)} no longer exists (rebased?). Showing last 20 commits.`, 'warn');
+      // Fall through — baseCommit effectively null
+    } else if (baseCommit === headHash) {
+      // HEAD is the deployed commit — only uncommitted changes matter
+      commitInfo = {
+        base: baseCommit.slice(0, 8),
+        head: headHash.slice(0, 8),
+        commits: [],
+        count: 0,
+        note: 'HEAD matches last deployed commit',
+      };
+    } else {
+      // Normal case: diff committed files between last deploy and HEAD
+      const diff = await capture(
+        `git diff --name-only ${baseCommit}..HEAD -- force-app/`, [], { cwd: root }
+      );
+      committedFiles = diff.stdout.split('\n').filter(f => f.startsWith('force-app/'));
+
+      const log = await capture(
+        `git log --oneline ${baseCommit}..HEAD`, [], { cwd: root }
+      );
+      const commits = log.stdout.split('\n').filter(Boolean).map(line => ({
+        hash:    line.slice(0, 7),
+        message: line.slice(8),
+      }));
+
+      commitInfo = {
+        base:    baseCommit.slice(0, 8),
+        head:    headHash.slice(0, 8),
+        commits,
+        count:   commits.length,
+        note:    null,
+      };
+    }
+  } else {
+    // No deploy record — show recent commit history and let user see what would deploy
+    const log = await capture('git log --oneline -20 -- force-app/', [], { cwd: root });
+    const commits = log.stdout.split('\n').filter(Boolean).map(line => ({
+      hash:    line.slice(0, 7),
+      message: line.slice(8),
+    }));
+
+    if (commits.length > 0) {
+      // Diff from the parent of the oldest visible commit
+      const oldest = commits[commits.length - 1].hash;
+      const diff = await capture(
+        `git diff --name-only ${oldest}~1..HEAD -- force-app/ 2>/dev/null || git diff --name-only ${oldest}..HEAD -- force-app/`,
+        [], { cwd: root, shell: true }
+      );
+      committedFiles = diff.stdout.split('\n').filter(f => f.startsWith('force-app/'));
+    }
+
+    commitInfo = {
+      base:    null,
+      head:    headHash.slice(0, 8),
+      commits,
+      count:   commits.length,
+      note:    'No deploy record — showing all recent changes (last 20 commits)',
+    };
+  }
+
+  const allFiles = [...new Set([...committedFiles, ...uncommittedFiles])];
+
+  // Convert file paths → Salesforce metadata refs, deduplicate
+  const metaMap = new Map();
+  for (const filePath of allFiles) {
+    const meta = filePathToMetadata(filePath);
+    if (meta && !metaMap.has(meta.ref)) metaMap.set(meta.ref, meta);
+  }
+
+  return {
+    components:       [...metaMap.values()].sort((a, b) => a.type.localeCompare(b.type)),
+    commitInfo,
+    uncommittedCount: uncommittedFiles.length,
+  };
+}
+
+// ─── Show changed component list + commit range before confirming ─────────────
+
+function showChangedComponents(scan, isDryRun) {
+  const { components, commitInfo, uncommittedCount } = scan;
+  const bar  = chalk.dim('  ┃  ');
+  const verb = isDryRun ? 'Will validate' : 'Will deploy';
+
+  console.log('');
+  console.log(chalk.cyan.bold(`  ┃  ${verb}  ${components.length} component(s)`));
+  console.log(chalk.dim('  ┃'));
+
+  // ── Commit range ─────────────────────────────────────────────────────────────
+  if (commitInfo) {
+    if (commitInfo.note) {
+      console.log(`${bar}${chalk.yellow(commitInfo.note)}`);
+    }
+
+    if (commitInfo.base) {
+      console.log(`${bar}${chalk.dim('Last deployed')}  ${chalk.white(commitInfo.base)}`);
+    }
+    console.log(`${bar}${chalk.dim('Current HEAD ')}  ${chalk.white(commitInfo.head || '?')}`);
+
+    if (commitInfo.commits.length > 0) {
+      console.log(chalk.dim('  ┃'));
+      console.log(`${bar}${chalk.cyan.bold(`${commitInfo.count} commit(s) not yet deployed`)}`);
+      commitInfo.commits.forEach(c => {
+        console.log(`${bar}  ${chalk.dim(c.hash)}  ${chalk.white(c.message)}`);
+      });
+    } else if (commitInfo.count === 0 && !commitInfo.note) {
+      console.log(`${bar}${chalk.dim('No new commits since last deploy')}`);
+    }
+
+    if (uncommittedCount > 0) {
+      console.log(chalk.dim('  ┃'));
+      console.log(`${bar}${chalk.yellow(`+${uncommittedCount} uncommitted file(s) also included`)}`);
+    }
+
+    console.log(chalk.dim('  ┃'));
+  }
+
+  // ── Files grouped by metadata type ───────────────────────────────────────────
+  console.log(`${bar}${chalk.cyan.bold('Components to deploy')}`);
+  const byType = {};
+  components.forEach(c => {
+    if (!byType[c.type]) byType[c.type] = [];
+    byType[c.type].push(c.name);
+  });
+
+  Object.entries(byType).forEach(([type, names]) => {
+    console.log(`${bar}  ${chalk.cyan(type)}  ${chalk.dim(`(${names.length})`)}`);
+    names.forEach(n => console.log(`${bar}    ${chalk.white(n)}`));
+  });
+
+  console.log(chalk.dim('  ┃'));
+  console.log('');
+}
+
+// ─── Empty state: no changes since last deploy ────────────────────────────────
+
+function showEmptyDeployState(scan) {
+  const { commitInfo, uncommittedCount } = scan;
+  const bar = chalk.dim('  ┃  ');
+
+  console.log('');
+  console.log(chalk.green.bold('  ┃  Nothing to deploy'));
+  console.log(chalk.dim('  ┃'));
+
+  if (commitInfo?.base) {
+    console.log(`${bar}${chalk.dim('Last deployed at')}  ${chalk.white(commitInfo.base)}`);
+    console.log(`${bar}${chalk.dim('Current HEAD   ')}  ${chalk.white(commitInfo.head || '?')}`);
+    console.log(`${bar}${chalk.green('All committed changes are already deployed.')}`);
+  } else {
+    console.log(`${bar}${chalk.dim('No deploy record found and no Salesforce files changed.')}`);
+  }
+
+  if (uncommittedCount === 0) {
+    console.log(`${bar}${chalk.dim('No uncommitted changes in force-app/ either.')}`);
+  }
+
+  console.log(chalk.dim('  ┃'));
+  console.log('');
+  logActivity('PIPELINE', 'Use "Full Deploy" or "Deploy Specific Class" if you want to redeploy.', 'info');
+}
+
+/**
+ * Convert a force-app file path to a deploy descriptor.
+ *
+ * Returns:
+ *   {
+ *     ref:       'ApexClass:UserService'      ← deduplication + display key
+ *     type:      'ApexClass'                   ← display grouping
+ *     name:      'UserService'                ← display name
+ *     sourceDir: 'force-app/main/default/...'  ← path passed to --source-dir
+ *   }
+ *
+ * Using --source-dir instead of --metadata ensures SF CLI discovers ALL files
+ * in the deploy unit (object fields, LWC assets, etc.) from the filesystem —
+ * nothing is silently dropped because of a missing regex branch.
+ *
+ * sourceDir rules:
+ *   - LWC / Aura  : component directory  (deploys all assets in one shot)
+ *   - CustomObject: object directory      (deploys fields, rules, layouts, etc.)
+ *   - Apex / single-file metadata: the specific file (not the whole folder)
+ *   - Unknown force-app/ file : the file itself — SF CLI determines type
+ *
+ * Returns null only for non-SF files (tests, docs, config outside force-app/).
+ */
+function filePathToMetadata(filePath) {
+  const p = filePath.replace(/\\/g, '/');
+
+  // Only process files inside force-app/
+  if (!p.includes('/force-app/') && !p.startsWith('force-app/')) return null;
+
+  // Helper — builds the descriptor.
+  // sourceDir defaults to filePath when not separately specified.
+  const make = (type, name, sourceDir) => ({
+    ref: `${type}:${name}`,
+    type,
+    name,
+    sourceDir: (sourceDir || filePath).replace(/\\/g, '/'),
+  });
+
+  // Extract the directory up to (and including) a named container folder.
+  // e.g. filePath='force-app/main/default/lwc/myComp/myComp.js'
+  //      → containerDir('lwc') = 'force-app/main/default/lwc/myComp'
+  const containerDir = (folder) => {
+    const m = p.match(new RegExp(`(.*/${folder}/[^/]+)`));
+    return m ? m[1] : filePath;
+  };
+
+  // ── Apex ──────────────────────────────────────────────────────────────────────
+  const cls = p.match(/\/classes\/([^/]+?)(?:\.cls(?:-meta\.xml)?)?$/);
+  if (cls) {
+    const name = cls[1].replace(/\.cls.*$/, '');
+    // Normalise to .cls (not -meta.xml) so SF CLI finds the right source file
+    const src  = filePath.replace(/\.cls-meta\.xml$/, '.cls');
+    return make('ApexClass', name, src);
+  }
+
+  const trg = p.match(/\/triggers\/([^/]+?)(?:\.trigger(?:-meta\.xml)?)?$/);
+  if (trg) {
+    const name = trg[1].replace(/\.trigger.*$/, '');
+    return make('ApexTrigger', name, filePath.replace(/\.trigger-meta\.xml$/, '.trigger'));
+  }
+
+  const page = p.match(/\/pages\/([^/]+?)(?:\.page(?:-meta\.xml)?)?$/);
+  if (page) {
+    const name = page[1].replace(/\.page.*$/, '');
+    return make('ApexPage', name, filePath.replace(/\.page-meta\.xml$/, '.page'));
+  }
+
+  // ── LWC / Aura — deploy the COMPONENT DIRECTORY so all assets are included ──
+  if (p.includes('/lwc/')) {
+    const m = p.match(/\/lwc\/([^/]+)/);
+    if (m) return make('LightningComponentBundle', m[1], containerDir('lwc'));
+  }
+
+  if (p.includes('/aura/')) {
+    const m = p.match(/\/aura\/([^/]+)/);
+    if (m) return make('AuraDefinitionBundle', m[1], containerDir('aura'));
+  }
+
+  // ── Objects — deploy the OBJECT DIRECTORY so ALL sub-types are included ──────
+  // Covers: fields, validationRules, listViews, recordTypes, webLinks, fieldSets,
+  //         compactLayouts, sharingReasons, businessProcesses, standardFields,
+  //         indexes, searchLayouts, territory2Types — everything in the folder.
+  if (p.includes('/objects/')) {
+    const objDir = p.match(/(.*\/objects\/[^/]+)/);
+    const objName = p.match(/\/objects\/([^/]+)/);
+    if (objDir && objName) return make('CustomObject', objName[1], objDir[1]);
+  }
+
+  // ── Flows & process builder ───────────────────────────────────────────────────
+  const flow = p.match(/\/flows\/([^/]+?)(?:\.flow-meta\.xml)?$/);
+  if (flow) return make('Flow', flow[1].replace(/\.flow.*$/, ''));
+
+  // ── Static resources ─────────────────────────────────────────────────────────
+  const sr = p.match(/\/staticresources\/([^/]+?)(?:\.|\/)/);
+  if (sr) return make('StaticResource', sr[1]);
+
+  // ── Permission sets & profiles ────────────────────────────────────────────────
+  const perm = p.match(/\/permissionsets\/([^/]+?)(?:\.permissionset-meta\.xml)?$/);
+  if (perm) return make('PermissionSet', perm[1].replace(/\.permissionset.*$/, ''));
+
+  const profile = p.match(/\/profiles\/([^/]+?)(?:\.profile-meta\.xml)?$/);
+  if (profile) return make('Profile', profile[1].replace(/\.profile.*$/, ''));
+
+  // ── Custom labels ─────────────────────────────────────────────────────────────
+  if (p.includes('/labels/')) return make('CustomLabels', 'CustomLabels');
+
+  // ── Layouts ───────────────────────────────────────────────────────────────────
+  const layout = p.match(/\/layouts\/([^/]+?)(?:\.layout-meta\.xml)?$/);
+  if (layout) return make('Layout', layout[1].replace(/\.layout.*$/, ''));
+
+  // ── Flex pages (App Builder) ──────────────────────────────────────────────────
+  const flexi = p.match(/\/flexiPages\/([^/]+?)(?:\.flexipage-meta\.xml)?$/);
+  if (flexi) return make('FlexiPage', flexi[1].replace(/\.flexipage.*$/, ''));
+
+  // ── Custom metadata records ───────────────────────────────────────────────────
+  const cmdType = p.match(/\/customMetadata\/([^/]+?)(?:\.md-meta\.xml)?$/);
+  if (cmdType) return make('CustomMetadata', cmdType[1].replace(/\.md.*$/, ''));
+
+  // ── Custom metadata types (object-like) ──────────────────────────────────────
+  const cmdTypeDef = p.match(/\/customMetadataTypes\/([^/]+?)(?:\.object-meta\.xml)?$/);
+  if (cmdTypeDef) return make('CustomObject', cmdTypeDef[1].replace(/\.object.*$/, ''));
+
+  // ── Named credentials ─────────────────────────────────────────────────────────
+  const nc = p.match(/\/namedCredentials\/([^/]+?)(?:\.namedCredential-meta\.xml)?$/);
+  if (nc) return make('NamedCredential', nc[1].replace(/\.namedCredential.*$/, ''));
+
+  // ── Remote site settings ──────────────────────────────────────────────────────
+  const rss = p.match(/\/remoteSiteSettings\/([^/]+?)(?:\.remoteSite-meta\.xml)?$/);
+  if (rss) return make('RemoteSiteSetting', rss[1].replace(/\.remoteSite.*$/, ''));
+
+  // ── Custom tabs ───────────────────────────────────────────────────────────────
+  const tab = p.match(/\/tabs\/([^/]+?)(?:\.tab-meta\.xml)?$/);
+  if (tab) return make('CustomTab', tab[1].replace(/\.tab.*$/, ''));
+
+  // ── Custom applications ───────────────────────────────────────────────────────
+  const app = p.match(/\/applications\/([^/]+?)(?:\.app-meta\.xml)?$/);
+  if (app) return make('CustomApplication', app[1].replace(/\.app.*$/, ''));
+
+  // ── Global / Standard value sets ─────────────────────────────────────────────
+  const gvs = p.match(/\/globalValueSets\/([^/]+?)(?:\.globalValueSet-meta\.xml)?$/);
+  if (gvs) return make('GlobalValueSet', gvs[1].replace(/\.globalValueSet.*$/, ''));
+
+  const svs = p.match(/\/standardValueSets\/([^/]+?)(?:\.standardValueSet-meta\.xml)?$/);
+  if (svs) return make('StandardValueSet', svs[1].replace(/\.standardValueSet.*$/, ''));
+
+  // ── Lightning message channels ────────────────────────────────────────────────
+  const lmc = p.match(/\/messageChannels\/([^/]+?)(?:\.messageChannel-meta\.xml)?$/);
+  if (lmc) return make('LightningMessageChannel', lmc[1].replace(/\.messageChannel.*$/, ''));
+
+  // ── Content assets ────────────────────────────────────────────────────────────
+  const asset = p.match(/\/contentassets\/([^/]+?)(?:\.|\/)/);
+  if (asset) return make('ContentAsset', asset[1]);
+
+  // ── Email templates ───────────────────────────────────────────────────────────
+  const email = p.match(/\/email\/(.+?)(?:\.email-meta\.xml)?$/);
+  if (email) return make('EmailTemplate', email[1].replace(/\.email.*$/, ''));
+
+  // ── Queues ────────────────────────────────────────────────────────────────────
+  const queue = p.match(/\/queues\/([^/]+?)(?:\.queue-meta\.xml)?$/);
+  if (queue) return make('Queue', queue[1].replace(/\.queue.*$/, ''));
+
+  // ── Groups ────────────────────────────────────────────────────────────────────
+  const group = p.match(/\/groups\/([^/]+?)(?:\.group-meta\.xml)?$/);
+  if (group) return make('Group', group[1].replace(/\.group.*$/, ''));
+
+  // ── Experience bundles (communities) ─────────────────────────────────────────
+  if (p.includes('/experiences/')) {
+    const m = p.match(/\/experiences\/([^/]+)/);
+    if (m) return make('ExperienceBundle', m[1], containerDir('experiences'));
+  }
+
+  // ── Catch-all: any other force-app/ file ─────────────────────────────────────
+  // Return it as-is so SF CLI can determine the type. Never silently drop a file.
+  const anyMeta = p.match(/\/force-app\/.*\/([^/]+?)(?:-meta\.xml)?$/);
+  if (anyMeta) {
+    const name = anyMeta[1].replace(/-meta\.xml$/, '');
+    return make('Metadata', name);
+  }
+
+  return null;
+}
+
+// ─── Core orchestration loop ───────────────────────────────────────────────────
+
+async function runDeployWithOrchestration(command, label, isDryRun, changedComponents) {
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+
+    if (attempt > 1) {
+      logActivity('PIPELINE', `Re-deploying after fixes  (attempt ${attempt} of ${MAX_ATTEMPTS})...`);
+    }
+
+    logActivity('PIPELINE', `${label}...`);
+    const result = await executeDeploy(command, label, attempt);
+
+    // ── Success ──────────────────────────────────────────────────────────────────
+    if (result.success) {
+      spinner.succeed(`${isDryRun ? 'Validation' : 'Deploy'} succeeded  ·  ${result.deployed} component(s)`);
+      if (!isDryRun) await celebrate('deploy_success');
+      logActivity('PIPELINE', `${isDryRun ? 'Dry run validation' : 'Deploy'} complete`, 'success');
+      if (!isDryRun) await saveDeployedCommit();
+      printActivityFooter();
+      return;
+    }
+
+    // ── Failure ──────────────────────────────────────────────────────────────────
+    spinner.fail(`${isDryRun ? 'Validation' : 'Deploy'} failed`);
+    if (!isDryRun) await celebrate('deploy_failed');
+
+    if (result.parseError) {
+      printError(`Could not parse deploy output — check org authentication.\n  ${result.parseError.slice(0, 300)}`);
+      return;
+    }
+
+    printDeployErrorPanel(result.componentErrors, result.testFailures, attempt, MAX_ATTEMPTS, result.rawErrors);
+
+    // Log full structured error detail to session log for audit
+    const errorDetail = [
+      `Command: ${command}`,
+      `Attempt: ${attempt} of ${MAX_ATTEMPTS}`,
+      '',
+      `Compile Errors (${result.componentErrors.length}):`,
+      ...result.componentErrors.map(e => `  ${e.fileName}:${e.lineNumber || '?'}  ${e.problem}`),
+      '',
+      `Test Failures (${result.testFailures.length}):`,
+      ...result.testFailures.map(f => `  ${f.name}.${f.methodName}  ${f.message || ''}`),
+      '',
+      result.rawErrors ? `Raw Output:\n${result.rawErrors}` : '',
+    ].filter(l => l !== undefined).join('\n');
+    logRawBlock('PIPELINE', `Deploy Error Detail — attempt ${attempt}`, errorDetail);
+
+    if (isDryRun) {
+      logActivity('PIPELINE', 'Fix the errors above, then run a deploy.');
+      printActivityFooter();
+      return;
+    }
+
+    // ── No actionable errors → infra/auth/CLI issue, not fixable by Copilot ────
+    const hasActionableErrors = result.componentErrors.length > 0 || result.testFailures.length > 0;
+    if (!hasActionableErrors) {
+      logActivity('PIPELINE', 'Deploy failed with no compile or test errors — not a code issue.', 'warn');
+      logActivity('PIPELINE', 'Likely causes:', 'warn');
+      logActivity('PIPELINE', '  1. SF CLI outdated — run: sf update', 'warn');
+      logActivity('PIPELINE', '  2. Org auth expired — run: sf org login web', 'warn');
+      logActivity('PIPELINE', '  3. Another deploy already in progress — run: sf project deploy cancel', 'warn');
+      logActivity('PIPELINE', '  4. Org sandbox maintenance — check trust.salesforce.com', 'warn');
+      printActivityFooter();
+      return;
+    }
+
+    if (attempt === MAX_ATTEMPTS) {
+      logActivity('PIPELINE', `Max auto-fix attempts (${MAX_ATTEMPTS}) reached.`, 'warn');
+      logActivity('PIPELINE', 'Review the errors manually and try again.', 'warn');
+      printActivityFooter();
+      return;
+    }
+
+    // ── Auto-orchestrate: Gemini analyzes → Copilot fixes → Gemini validates → redeploy ──
+    await autoCountdown('Auto-orchestrating  ·  Gemini → Copilot → Gemini → redeploy  ·  Ctrl+C to abort');
+
+    const fixFile = await geminiAnalyzeErrors(result, command, attempt);
+    if (!fixFile) { logActivity('GEMINI', 'Analysis failed — fix manually and retry.', 'error'); return; }
+
+    // ── Guard: detect empty/failed fix guide before sending to Copilot ────────
+    // When Gemini fails (429 / capacity error), the output file is written but
+    // contains only headers or an error message — not real fix instructions.
+    // Sending an empty fix guide to Copilot causes it to do nothing.
+    const fixGuideRaw   = existsSync(fixFile) ? readFileSync(fixFile, 'utf8') : '';
+    const fixGuideWords = fixGuideRaw.replace(/[#\-*=\s]/g, '').length; // meaningful chars
+    if (fixGuideRaw.length < 100 || fixGuideWords < 80) {
+      logActivity('GEMINI', `Fix guide appears empty or incomplete (${fixGuideWords} meaningful chars).`, 'error');
+      logActivity('GEMINI', 'Gemini likely hit a capacity error (429). Check session log for details.', 'error');
+      logActivity('GEMINI', 'Options: wait and retry, or set GEMINI_MODEL=gemini-2.5-pro and retry.', 'warn');
+      const { continueEmpty } = await inquirer.prompt([{
+        type:    'confirm',
+        name:    'continueEmpty',
+        message: 'Fix guide is empty — Copilot will do nothing. Retry this attempt anyway?',
+        default: false,
+      }]);
+      if (!continueEmpty) {
+        logActivity('PIPELINE', 'Paused — resolve Gemini error and retry deploy.');
+        printActivityFooter();
+        return;
+      }
+    }
+
+    // ── Copilot applies the fixes (Claude = Architect only) ───────────────────
+    const relFixPath = fixFile.replace(getRootDir() + '/', '');
+    logActivity('COPILOT', `Dispatching fix guide to Copilot from ${relFixPath}...`);
+
+    const stopCopilotFix = spinCycle('Copilot', [
+      'Reading deploy error analysis...',
+      'Fixing compile errors in Apex classes...',
+      'Fixing test class failures...',
+      'Saving all changes...',
+    ], 5000, 'blue');
+
+    // Build Copilot prompt with BOTH the raw errors AND Gemini's fix guide.
+    // Raw errors = ground truth (exact file:line for every error).
+    // Fix guide  = Gemini's root-cause analysis and how-to-fix instructions.
+    // Copilot must address every raw error — not just the ones Gemini mentioned.
+    const fixGuideContent = existsSync(fixFile) ? readFileSync(fixFile, 'utf8') : '(fix guide not found)';
+    const rawErrorsList   = formatErrorsForCopilot(result);
+
+    const copilotPrompt =
+      `You are a Salesforce Apex developer. Fix ALL the deployment errors listed below.\n\n` +
+      `IMPORTANT: This is a fresh task — ignore any prior context. Make the exact changes described below.\n\n` +
+      `=== DEPLOY ERRORS (GROUND TRUTH — fix EVERY one of these) ===\n${rawErrorsList}\n=== END ERRORS ===\n\n` +
+      `=== FIX GUIDE (Gemini's root-cause analysis and instructions) ===\n${fixGuideContent}\n=== END FIX GUIDE ===\n\n` +
+      `MANDATORY SEARCH RULES — follow these before making ANY change:\n` +
+      `1. NEVER guess a file name, class name, method name, or field name.\n` +
+      `2. Before editing any file: use your search/read tools to locate and open the ACTUAL file.\n` +
+      `   - Search by name: find force-app/ -name "*ClassName*"\n` +
+      `   - If a line number is given, open the file and verify the line content before editing.\n` +
+      `3. Before changing any field reference: read the object metadata XML under\n` +
+      `   force-app/main/default/objects/<ObjectName>/fields/ to confirm the field API name exists.\n` +
+      `   Do NOT invent or assume field names — only use names confirmed in the metadata files.\n` +
+      `4. Read ±20 lines of context around each error location before applying a fix.\n` +
+      `5. For each error: search for ALL occurrences of the same incorrect pattern in the entire file,\n` +
+      `   not just the reported line number — fix every occurrence.\n` +
+      `6. If you cannot find a file or symbol after searching, log "NOT FOUND: <name>" and skip it.\n` +
+      `   Do NOT create stub code to fill a gap.\n\n` +
+      `Fix Steps:\n` +
+      `1. Work through each error in the DEPLOY ERRORS section above, one by one\n` +
+      `2. Use the FIX GUIDE for the root-cause explanation and recommended fix\n` +
+      `3. Open the ACTUAL file, verify the error line, fix ALL occurrences in the file\n` +
+      `4. Save the file, then move to the next error\n` +
+      `5. Do NOT refactor or change anything outside the listed errors`;
+
+    // Log the exact prompt sent to Copilot so we can audit what it received
+    logRawBlock('COPILOT', `Prompt Sent to Copilot — attempt ${attempt}`, copilotPrompt);
+
+    const copilotStart = Date.now();
+    await runCopilot(copilotPrompt, {} /* No featureId → fresh session each deploy-fix attempt */);
+    const copilotElapsed = Date.now() - copilotStart;
+
+    stopCopilotFix();
+
+    // If Copilot finishes in under 10s it almost certainly didn't run (not found, crashed, etc.)
+    if (copilotElapsed < 10000) {
+      spinner.warn(`Copilot finished in ${(copilotElapsed / 1000).toFixed(1)}s — may not have run`);
+      logActivity('COPILOT', `Completed in ${(copilotElapsed / 1000).toFixed(1)}s — check that 'copilot' CLI is installed and in PATH`, 'warn');
+      const { continueAnyway } = await inquirer.prompt([{
+        type:    'confirm',
+        name:    'continueAnyway',
+        message: 'Copilot may not have applied fixes. Continue to validation anyway?',
+        default: false,
+      }]);
+      if (!continueAnyway) {
+        logActivity('PIPELINE', 'Paused — verify Copilot CLI is installed: which copilot');
+        printActivityFooter();
+        return;
+      }
+    } else {
+      spinner.succeed('Copilot finished applying fixes');
+      logActivity('COPILOT', 'All fixes applied', 'success');
+    }
+
+    const validated = await geminiValidateFixes(result, fixFile, attempt);
+
+    if (!validated.approved) {
+      logActivity('GEMINI', `Validation: ${validated.verdict}  ·  ${validated.issues} issue(s) remain.`, 'warn');
+      if (validated.issues > 0) {
+        const { retryFix } = await inquirer.prompt([{
+          type:    'confirm',
+          name:    'retryFix',
+          message: 'Gemini found remaining issues. Redeploy anyway?',
+          default: false,
+        }]);
+        if (!retryFix) {
+          logActivity('PIPELINE', 'Deployment paused — fix remaining issues and retry.');
+          printActivityFooter();
+          return;
+        }
+      }
+    } else {
+      logActivity('GEMINI', 'Fixes validated — all errors addressed', 'success');
+    }
+    // loop → redeploy
+  }
+}
+
+// ─── Deploy executor ───────────────────────────────────────────────────────────
+
+async function executeDeploy(command, label, attempt) {
+  // ── Spawn deploy with piped output so we capture the final JSON ──────────
+  const proc = spawn(`${command} --json`, [], {
+    cwd:   getRootDir(),
+    shell: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env:   { ...process.env },
+  });
+
+  let stdoutBuf = '';
+  let stderrBuf = '';
+  proc.stdout?.on('data', d => { stdoutBuf += d.toString(); });
+  proc.stderr?.on('data', d => { stderrBuf += d.toString(); });
+
+  // ── Minimal spinner — real progress comes from polling below ─────────────
+  const stopCycle = spinCycle('Deploy',
+    attempt === 1
+      ? ['Waiting for org response...', 'Compiling Apex...', 'Running tests...', 'Almost done...']
+      : ['Re-deploying...', 'Compiling Apex...', 'Running tests...', 'Checking results...'],
+    6000, 'yellow'
+  );
+
+  // ── Poll sf project deploy report every 4s for real-time detail ──────────
+  // Tracks shown items so we never print the same component/test twice.
+  const shownComponents = new Set();
+  const shownTests      = new Set();
+  let lastNumDeployed   = -1;
+  let lastNumTests      = -1;
+
+  const poll = setInterval(async () => {
+    try {
+      const r = await capture('sf project deploy report --json 2>/dev/null');
+      if (!r.stdout?.trim()) return;
+
+      const json = JSON.parse(r.stdout);
+      const res  = json.result || {};
+      if (!res.status || res.status === 'Pending') return;
+
+      const numDeployed = res.numberComponentsDeployed ?? 0;
+      const numTotal    = res.numberComponentsTotal    ?? 0;
+      const numTests    = res.numberTestsCompleted     ?? 0;
+      const numTotalT   = res.numberTestsTotal         ?? 0;
+
+      // ── Component progress ──────────────────────────────────────────────
+      if (numTotal > 0 && numDeployed !== lastNumDeployed) {
+        lastNumDeployed = numDeployed;
+        const pct = Math.round((numDeployed / numTotal) * 100);
+        logActivity('PIPELINE', `Components  ${numDeployed}/${numTotal}  (${pct}%)`, 'info');
+
+        // Each newly deployed component
+        const successes = res.details?.componentSuccesses || [];
+        for (const c of successes) {
+          const key = `${c.componentType}:${c.fullName}`;
+          if (!shownComponents.has(key)) {
+            shownComponents.add(key);
+            logActivity('PIPELINE', `  ✓  ${c.componentType}:${c.fullName}`, 'success');
+          }
+        }
+
+        // Component failures — show immediately as they appear
+        const failures = (res.details?.componentFailures || [])
+          .filter(f => f.problemType === 'Error' || !f.problemType);
+        for (const f of failures) {
+          const key = `ERR:${f.fullName}:${f.lineNumber}`;
+          if (!shownComponents.has(key)) {
+            shownComponents.add(key);
+            logActivity('PIPELINE',
+              `  ✗  ${f.fullName}  line ${f.lineNumber || '?'}  ${(f.problem || '').slice(0, 100)}`,
+              'error'
+            );
+          }
+        }
+      }
+
+      // ── Test progress ───────────────────────────────────────────────────
+      if (numTotalT > 0 && numTests !== lastNumTests) {
+        lastNumTests = numTests;
+        logActivity('PIPELINE', `Tests  ${numTests}/${numTotalT}`, 'info');
+
+        // Each newly passed test method
+        const testSuccesses = res.details?.runTestResult?.successes || [];
+        for (const t of testSuccesses) {
+          const key = `TP:${t.name}.${t.methodName}`;
+          if (!shownTests.has(key)) {
+            shownTests.add(key);
+            logActivity('PIPELINE', `  ✓  ${t.name}.${t.methodName}`, 'success');
+          }
+        }
+
+        // Each newly failed test — show immediately
+        const testFailures = res.details?.runTestResult?.failures || [];
+        for (const t of testFailures) {
+          const key = `TF:${t.name}.${t.methodName}`;
+          if (!shownTests.has(key)) {
+            shownTests.add(key);
+            logActivity('PIPELINE',
+              `  ✗  ${t.name}.${t.methodName}  ${(t.message || '').slice(0, 100)}`,
+              'error'
+            );
+          }
+        }
+      }
+    } catch { /* poll failed — non-fatal, deploy still runs */ }
+  }, 4000);
+
+  // ── Wait for deploy process to finish ────────────────────────────────────
+  await new Promise((resolvePromise, reject) => {
+    proc.on('close', resolvePromise);
+    proc.on('error', reject);
+  });
+
+  clearInterval(poll);
+  stopCycle();
+  spinner.stop();
+
+  return parseDeployResult({ stdout: stdoutBuf.trim(), stderr: stderrBuf.trim(), code: 0 });
+}
+
+// ─── Parse sf CLI JSON output ─────────────────────────────────────────────────
+
+function parseDeployResult(captureResult) {
+  // sf CLI sometimes writes JSON to stderr when the process exits non-zero
+  const rawJson = captureResult.stdout.trim() || captureResult.stderr.trim();
+
+  try {
+    const json = JSON.parse(rawJson);
+
+    // SF CLI top-level errors (e.g. ComponentSetError) have no `result` key —
+    // surface the message directly so the user sees a real error, not "0 errors".
+    if (!json.result && json.message) {
+      return {
+        success: false, status: json.name || 'Error', deployed: 0,
+        componentErrors: [], testFailures: [],
+        rawErrors: `${json.name || 'Error'}: ${json.message}`,
+        raw: rawJson,
+      };
+    }
+
+    const r    = json.result || {};
+
+    // componentFailures: all types (Error + Warning) — filter for actionable errors only
+    const comp = r.details?.componentFailures || [];
+    const errs = comp.filter(f => f.problemType === 'Error' || !f.problemType);
+
+    // Test failures can live at two paths depending on SF CLI version
+    const testResult = r.details?.runTestResult || r.runTestResult || {};
+    const tests      = testResult.failures || testResult.testFailures || [];
+
+    const succeeded  = r.status === 'Succeeded' || r.success === true;
+
+    // Build a plain-text summary of all failures for Gemini when structured arrays are empty
+    let rawErrors = '';
+    if (!succeeded && errs.length === 0 && tests.length === 0) {
+      // Collect any failure info from the JSON we do have
+      const msgs = [];
+      if (r.status) msgs.push(`Deploy status: ${r.status}`);
+      if (r.errorMessage) msgs.push(`Error: ${r.errorMessage}`);
+      if (r.errorStatusCode) msgs.push(`Code: ${r.errorStatusCode}`);
+      if (comp.length > 0) {
+        msgs.push(`Component issues (${comp.length}): ${comp.map(c => `${c.fullName}: ${c.problem}`).join('; ')}`);
+      }
+      // Strip known non-error lines (CLI update notices, blank lines) from stderr fallback
+      const cleanStderr = (captureResult.stderr || '')
+        .split('\n')
+        .filter(l => !/Warning:.*update available/i.test(l) && l.trim() !== '')
+        .join('\n')
+        .trim();
+      rawErrors = msgs.join('\n') || cleanStderr.slice(0, 800);
+    }
+
+    return {
+      success:         succeeded && errs.length === 0 && tests.length === 0,
+      status:          r.status || 'Unknown',
+      deployed:        (r.details?.componentSuccesses || []).length,
+      componentErrors: errs,
+      testFailures:    tests,
+      rawErrors,
+      raw:             rawJson,
+    };
+  } catch {
+    const combined = (captureResult.stdout + '\n' + captureResult.stderr).trim();
+    return {
+      success: false, status: 'Parse Error', deployed: 0,
+      componentErrors: [], testFailures: [],
+      rawErrors: combined.slice(0, 800),
+      parseError: combined.slice(0, 800), raw: combined,
+    };
+  }
+}
+
+// ─── Gemini: analyze deploy errors ────────────────────────────────────────────
+
+async function geminiAnalyzeErrors(deployResult, command, attempt) {
+  const geminiAvailable = await isAvailable('gemini');
+  const root            = getRootDir();
+  const workflowDir     = getWorkflowDir();
+  const geminiMd        = resolve(root, 'GEMINI.md');
+
+  if (!geminiAvailable || !existsSync(geminiMd)) {
+    logActivity('GEMINI', 'CLI not available — copy errors manually to Copilot.', 'warn');
+    return null;
+  }
+
+  logActivity('GEMINI', 'Analyzing deployment errors...');
+
+  const errorsText = formatErrorsForGemini(deployResult);
+
+  // ── Attach real object field lists for any "field does not exist" errors ──────
+  // This prevents Gemini from guessing field names — it gets the ground truth.
+  const objectFieldContext = buildObjectFieldContext(deployResult, root);
+
+  const context    = `${readFileSync(geminiMd, 'utf8')}
+
+## Task
+Analyze these Salesforce deployment errors and write specific fix instructions for GitHub Copilot.
+
+## Deploy Command
+\`${command}\`
+
+## Deployment Errors  (Attempt ${attempt})
+${errorsText}
+${objectFieldContext}
+## Required Output
+1. **Root Cause Analysis** — are multiple errors from one cause?
+2. **Fix Instructions** — numbered list with exact file path, line number, what to change and why. Use ONLY field names confirmed in the "Actual Fields" section above — do NOT guess or invent field names.
+3. **Verification Steps** — how Copilot confirms each fix is correct
+4. **Priority Order** — fix compile errors before test failures`;
+
+  const timestamp = Date.now();
+  const fixesDir  = resolve(workflowDir, 'deploy-fixes');
+  if (!existsSync(fixesDir)) mkdirSync(fixesDir, { recursive: true });
+
+  const fixFile  = resolve(fixesDir, `DEPLOYFIX-${timestamp}.md`);
+  const prompt   = context +
+    '\n\nAnalyze these Salesforce deployment errors and write a structured fix guide for GitHub Copilot. ' +
+    'Start your response directly with "## Root Cause Analysis" — do NOT include any planning steps, ' +
+    '"I will..." sentences, or meta-commentary. Output only the structured fix guide.';
+
+  const stopCycle = spinCycle('Gemini', [
+    'Reading deploy errors...',
+    'Identifying root causes...',
+    'Writing fix instructions for Copilot...',
+  ], 4000, 'cyan');
+
+  await runGemini(prompt, fixFile);
+
+  stopCycle();
+
+  // Strip any Gemini planning monologue ("I will..." lines) from the top of the file.
+  // These appear when Gemini outputs its thinking before the actual analysis.
+  if (existsSync(fixFile)) {
+    const raw = readFileSync(fixFile, 'utf8');
+    const lines = raw.split('\n');
+    // Find the first markdown heading (##) — that's where the real content starts
+    const firstHeading = lines.findIndex(l => /^#{1,3}\s/.test(l.trim()));
+    if (firstHeading > 0) {
+      writeFileSync(fixFile, lines.slice(firstHeading).join('\n'), 'utf8');
+    }
+  }
+
+  spinner.succeed(`Fix guide written → deploy-fixes/DEPLOYFIX-${timestamp}.md`);
+  logActivity('GEMINI', `.ai-workflow/deploy-fixes/DEPLOYFIX-${timestamp}.md`, 'success');
+
+  return fixFile;
+}
+
+// ─── Gemini: validate fixes ────────────────────────────────────────────────────
+
+async function geminiValidateFixes(originalErrors, fixFile, attempt) {
+  const geminiAvailable = await isAvailable('gemini');
+  const root            = getRootDir();
+  const workflowDir     = getWorkflowDir();
+  const geminiMd        = resolve(root, 'GEMINI.md');
+
+  if (!geminiAvailable || !existsSync(geminiMd)) return { approved: true, verdict: 'SKIPPED', issues: 0 };
+
+  logActivity('GEMINI', 'Validating Copilot fixes against original errors...');
+
+  const diffResult = await capture('git diff HEAD 2>/dev/null || git diff --cached 2>/dev/null', [], { cwd: root });
+  const diff       = diffResult.stdout || 'No git diff available';
+
+  const context = `${readFileSync(geminiMd, 'utf8')}
+
+## Task
+Validate that the code changes fix the Salesforce deployment errors listed below.
+
+## Original Errors
+${formatErrorsForGemini(originalErrors)}
+
+## Fix Guide (Gemini's instructions to Copilot)
+${existsSync(fixFile) ? readFileSync(fixFile, 'utf8') : 'Not available'}
+
+## Code Changes (git diff)
+\`\`\`diff
+${diff}
+\`\`\`
+
+## Required Output
+- **Verdict**: VALIDATED or NEEDS_MORE_WORK
+- **Summary**: one sentence
+- **Remaining Issues**: bullet list (empty if none)`;
+
+  const timestamp  = Date.now();
+  const validFile  = resolve(workflowDir, 'deploy-fixes', `VALIDATE-${timestamp}.md`);
+  const valPrompt  = context +
+    '\n\nValidate these code changes fix the listed Salesforce deploy errors. Output: VALIDATED or NEEDS_MORE_WORK with remaining issues.';
+
+  const stopCycle = spinCycle('Gemini', [
+    'Reviewing Copilot changes...',
+    'Checking each error is addressed...',
+    'Verifying no regressions...',
+  ], 4000, 'cyan');
+
+  await runGemini(valPrompt, validFile);
+
+  stopCycle();
+
+  const content  = existsSync(validFile) ? readFileSync(validFile, 'utf8') : '';
+  const approved = /\bVALIDATED\b/i.test(content) && !/NEEDS_MORE_WORK/i.test(content);
+  const issues   = (content.match(/^[-*]\s.+/mg) || []).length;
+
+  if (approved) spinner.succeed('Fixes validated — all errors addressed');
+  else          spinner.warn(`Gemini found ${issues} remaining issue(s)`);
+
+  logActivity('GEMINI', `Validation: ${approved ? 'VALIDATED' : 'NEEDS_MORE_WORK'}  ·  ${issues} remaining`, approved ? 'success' : 'warn');
+  return { approved, verdict: approved ? 'VALIDATED' : 'NEEDS_MORE_WORK', issues };
+}
+
+// ─── Helpers ───────────────────────────────────────────────────────────────────
+
+function formatErrorsForGemini(deployResult) {
+  const lines = [];
+  if (deployResult.componentErrors.length) {
+    lines.push(`### Compile Errors (${deployResult.componentErrors.length})`);
+    deployResult.componentErrors.forEach((e, i) => {
+      lines.push(`${i + 1}. **File:** \`${e.fileName || e.fullName}\`${e.lineNumber ? ` line ${e.lineNumber}` : ''}`);
+      lines.push(`   **Error:** ${e.problem}`);
+      lines.push('');
+    });
+  }
+  if (deployResult.testFailures.length) {
+    lines.push(`### Test Failures (${deployResult.testFailures.length})`);
+    deployResult.testFailures.forEach((f, i) => {
+      lines.push(`${i + 1}. **Test:** \`${f.name}.${f.methodName}\``);
+      lines.push(`   **Message:** ${f.message || ''}`);
+      if (f.stackTrace) lines.push(`   **Stack:** ${f.stackTrace.split('\n')[0]}`);
+      lines.push('');
+    });
+  }
+  // Fallback: when SF CLI doesn't return structured errors, include raw output
+  if (lines.length === 0 && deployResult.rawErrors) {
+    lines.push('### Raw Deploy Output (structured errors unavailable)');
+    lines.push(deployResult.rawErrors);
+  }
+  return lines.join('\n') || 'No errors captured — deploy may have failed due to org connectivity or auth.';
+}
+
+/**
+ * Format deploy errors as a compact, line-by-line list for Copilot.
+ * This is the GROUND TRUTH — every error with exact file + line number.
+ * Copilot must fix ALL of these, not just the ones Gemini mentioned in its guide.
+ */
+function formatErrorsForCopilot(deployResult) {
+  const lines = [];
+  if (deployResult.componentErrors.length) {
+    lines.push(`Compile Errors (${deployResult.componentErrors.length} — fix ALL of these):`);
+    deployResult.componentErrors.forEach((e, i) => {
+      const loc = e.lineNumber ? `:${e.lineNumber}` : '';
+      lines.push(`  ${i + 1}. ${e.fileName || e.fullName}${loc}  →  ${e.problem}`);
+    });
+  }
+  if (deployResult.testFailures.length) {
+    lines.push('');
+    lines.push(`Test Failures (${deployResult.testFailures.length} — fix ALL of these):`);
+    deployResult.testFailures.forEach((f, i) => {
+      lines.push(`  ${i + 1}. ${f.name}.${f.methodName}  →  ${f.message || '(no message)'}`);
+      if (f.stackTrace) lines.push(`     Stack: ${f.stackTrace.split('\n')[0]}`);
+    });
+  }
+  if (lines.length === 0 && deployResult.rawErrors) {
+    lines.push('Raw errors (structured parse failed):');
+    lines.push(deployResult.rawErrors.slice(0, 3000));
+  }
+  return lines.join('\n') || 'No structured errors — see fix guide for details.';
+}
+
+/**
+ * For every "field does not exist on <Object>" or "variable does not exist" error,
+ * look up the actual field names from local object metadata and include them in
+ * the Gemini context — so Gemini gives Copilot CORRECT field names, not guesses.
+ */
+function buildObjectFieldContext(deployResult, root) {
+  const objectsDir = resolve(root, 'force-app/main/default/objects');
+  if (!existsSync(objectsDir)) return '';
+
+  // Extract object names mentioned in errors (e.g. "on XConn__XConnection__c")
+  const allErrors = [
+    ...deployResult.componentErrors.map(e => e.problem || ''),
+    ...deployResult.testFailures.map(f => f.message || ''),
+    deployResult.rawErrors || '',
+  ].join('\n');
+
+  // Match patterns like "on XConnection__c", "on XConn__XConnection__c", "does not exist: SomeField__c on ObjName__c"
+  const objectMatches = new Set();
+  for (const m of allErrors.matchAll(/\bon\s+([\w]+__c)\b/gi)) objectMatches.add(m[1]);
+  // Also strip namespace prefix so we can find the local folder
+  for (const m of allErrors.matchAll(/\bon\s+\w+__([\w]+__c)\b/gi)) objectMatches.add(m[1]);
+
+  if (objectMatches.size === 0) return '';
+
+  const lines = ['\n## Actual Object Fields (ground truth — use ONLY these names)'];
+
+  for (const objName of objectMatches) {
+    // Try both namespaced and non-namespaced folder names
+    const candidates = [objName, `XConn__${objName}`];
+    for (const folder of candidates) {
+      const fieldsDir = resolve(objectsDir, folder, 'fields');
+      if (!existsSync(fieldsDir)) continue;
+      try {
+        const fieldFiles = readdirSync(fieldsDir).filter(f => f.endsWith('.field-meta.xml'));
+        const fieldNames = fieldFiles.map(f => f.replace('.field-meta.xml', ''));
+        lines.push(`\n### ${folder} — valid field API names`);
+        lines.push(fieldNames.map(f => `- ${f}`).join('\n'));
+      } catch { /* skip if unreadable */ }
+      break;
+    }
+  }
+
+  return lines.length > 1 ? lines.join('\n') + '\n' : '';
+}
+
+function showStatusReport(captureResult) {
+  try {
+    const json   = JSON.parse(captureResult.stdout);
+    const r      = json.result || {};
+    const status = r.status || r.deploymentStatus || 'Unknown';
+    const color  = status === 'Succeeded' ? 'green' : 'red';
+    const bar    = chalk.dim('  ┃  ');
+    console.log('');
+    console.log(chalk[color].bold(`  ┃  Last Deploy: ${status}`));
+    console.log(chalk.dim('  ┃'));
+    if (r.id) console.log(`${bar}${chalk.dim('ID')}  ${chalk.white(r.id)}`);
+    const succ = r.details?.componentSuccesses?.length ?? 0;
+    const fail = r.details?.componentFailures?.length ?? 0;
+    if (succ || fail) console.log(`${bar}${chalk.green(`${succ} succeeded`)}  ${chalk.dim('·')}  ${chalk.red(`${fail} failed`)}`);
+    console.log('');
+  } catch {
+    const out = captureResult.stdout || captureResult.stderr;
+    console.log(chalk.dim('\n' + out.slice(0, 500) + '\n'));
+  }
+}