viepilot 2.49.0 → 3.7.2

package/lib/intake/adapters/excel-m365.cjs

@@ -79,35 +79,55 @@ function httpsGet(url, headers) {
   });
 }
 
-/** Follow redirects and return {status, headers, body} */
-function httpsGetRaw(url, headers = {}, maxRedirects = 6) {
+/**
+ * Follow redirects and return {status, headers, body, cookies}.
+ * Cookies (Set-Cookie) are accumulated across all redirects and forwarded
+ * on each hop — required for SharePoint FedAuth session cookies.
+ */
+function httpsGetRaw(url, headers = {}, maxRedirects = 8) {
   return new Promise((resolve, reject) => {
-    function doGet(currentUrl, remaining) {
+    function doGet(currentUrl, remaining, accCookies) {
       const urlObj = new URL(currentUrl);
+      const reqHeaders = {
+        'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36',
+        ...headers,
+      };
+      if (accCookies) reqHeaders['Cookie'] = accCookies;
+
       const req = https.request({
         hostname: urlObj.hostname,
         path: urlObj.pathname + urlObj.search,
         method: 'GET',
-        headers: {
-          'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36',
-          ...headers,
-        },
+        headers: reqHeaders,
       }, (res) => {
+        // Accumulate Set-Cookie headers across redirects
+        const setCookies = (res.headers['set-cookie'] || []).map((c) => c.split(';')[0]);
+        const newCookies = setCookies.length
+          ? [accCookies, ...setCookies].filter(Boolean).join('; ')
+          : accCookies;
+
         if ([301, 302, 303, 307, 308].includes(res.statusCode) && res.headers.location && remaining > 0) {
           let nextUrl = res.headers.location;
           if (!nextUrl.startsWith('http')) {
             nextUrl = `${urlObj.protocol}//${urlObj.host}${nextUrl}`;
           }
-          return doGet(nextUrl, remaining - 1);
+          // Drain response body before following redirect
+          res.resume();
+          return doGet(nextUrl, remaining - 1, newCookies);
         }
         const chunks = [];
         res.on('data', (chunk) => chunks.push(chunk));
-        res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, body: Buffer.concat(chunks) }));
+        res.on('end', () => resolve({
+          status: res.statusCode,
+          headers: res.headers,
+          body: Buffer.concat(chunks),
+          cookies: newCookies,
+        }));
       });
       req.on('error', reject);
       req.end();
     }
-    doGet(url, maxRedirects);
+    doGet(url, maxRedirects, '');
   });
 }
 
@@ -166,7 +186,7 @@ async function readViaGraphApi(channel, projectRoot) {
   const response = await httpsGet(url, { Authorization: `Bearer ${token}` });
 
   if (!response.values || response.values.length === 0) return [];
-  return parseRowsWithColumnMap(response.values, channel.column_map);
+  return parseRowsWithColumnMap(response.values, channel.column_map, channel.id);
 }
 
 // ─── SharePoint sharing link (anonymous WOPI) ─────────────────────────────────
@@ -177,12 +197,13 @@ function isSharingLink(url) {
 }
 
 /**
- * Resolve a SharePoint anonymous sharing link to a direct download URL.
+ * Resolve a SharePoint anonymous sharing link to {downloadUrl, cookies}.
  * Technique: load WOPI viewer page → scrape FileGetUrl (temp auth token embedded in HTML).
+ * Returns the cookies collected during the redirect chain — they must be forwarded
+ * when downloading (SharePoint FedAuth cookie is required for download.aspx).
  */
 async function resolveSharePointDownloadUrl(sharingUrl) {
-  // First request: follow redirects to the WOPI viewer page
-  const { status, body } = await httpsGetRaw(sharingUrl);
+  const { status, body, cookies } = await httpsGetRaw(sharingUrl);
   if (status !== 200) {
     throw new Error(`SharePoint sharing link returned HTTP ${status}. The link may be expired or restricted.`);
   }
@@ -195,19 +216,35 @@ async function resolveSharePointDownloadUrl(sharingUrl) {
     throw new Error('Could not extract download URL from SharePoint viewer page. The file may require sign-in.');
   }
 
-  // Unescape JSON unicode escapes (\\u0026 → &)
-  return match[1].replace(/\\u([\da-fA-F]{4})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+  // Unescape JSON unicode escapes (& → &)
+  const downloadUrl = match[1].replace(/\\u([\da-fA-F]{4})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+  return { downloadUrl, cookies };
 }
 
-/** Download xlsx bytes from a URL (no auth, temp token already embedded) */
-async function downloadXlsx(downloadUrl) {
-  const { status, body } = await httpsGetRaw(downloadUrl, {
-    Accept: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,*/*',
-  });
+/**
+ * Download xlsx bytes.
+ * cookies: FedAuth cookies from WOPI page — required for download.aspx redirect chain.
+ */
+async function downloadXlsx(downloadUrl, cookies) {
+  const extraHeaders = { Accept: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,*/*' };
+  const { status, body } = await httpsGetRaw(downloadUrl, extraHeaders, 8);
   if (status !== 200) {
+    // Retry with cookies if initial attempt fails (some SharePoint tenants need FedAuth)
+    if (cookies) {
+      const retry = await httpsGetRaw(downloadUrl, { ...extraHeaders, Cookie: cookies }, 8);
+      if (retry.status === 200 && retry.body.length > 100) return retry.body;
+    }
     throw new Error(`Failed to download xlsx: HTTP ${status}`);
   }
-  return body; // Buffer
+  // If we got HTML instead of binary (redirect page), retry with cookies
+  const magic = body.slice(0, 4).toString('hex');
+  if (magic !== '504b0304' && cookies) {
+    const retry = await httpsGetRaw(downloadUrl, { ...extraHeaders, Cookie: cookies }, 8);
+    if (retry.status === 200 && retry.body.slice(0, 4).toString('hex') === '504b0304') {
+      return retry.body;
+    }
+  }
+  return body;
 }
 
 // ─── xlsx parser (SheetJS) ────────────────────────────────────────────────────
@@ -249,23 +286,69 @@ function parseXlsxBuffer(buffer, sheetName) {
 
 async function readViaSharingLink(channel) {
   const sharingUrl = channel.sharing_url;
-  const downloadUrl = await resolveSharePointDownloadUrl(sharingUrl);
-  const xlsxBuffer = await downloadXlsx(downloadUrl);
+  const { downloadUrl, cookies } = await resolveSharePointDownloadUrl(sharingUrl);
+  const xlsxBuffer = await downloadXlsx(downloadUrl, cookies);
   const rows = parseXlsxBuffer(xlsxBuffer, channel.sheet_name || null);
 
   if (!rows || rows.length === 0) return [];
-  return parseRowsWithColumnMap(rows, channel.column_map);
+  return parseRowsWithColumnMap(rows, channel.column_map, channel.id);
+}
+
+// ─── Vietnamese/English header → field name auto-detection ────────────────────
+
+const HEADER_ALIASES = {
+  id:          ['stt', 'id', 'no', '#', 'mã', 'ma'],
+  title:       ['title', 'tiêu đề', 'tieu de', 'tên', 'ten', 'màn hình', 'man hinh', 'tên module', 'tên testcase', 'summary'],
+  description: ['mô tả lỗi', 'mo ta loi', 'description', 'mô tả', 'mo ta', 'chi tiết', 'chi tiet', 'detail', 'nội dung', 'noi dung'],
+  status:      ['status', 'trạng thái', 'trang thai', 'kết quả', 'ket qua', 'result', 'p/f/n'],
+  reporter:    ['reporter', 'người báo', 'nguoi bao', 'tester', 'người tạo', 'nguoi tao'],
+  priority:    ['priority', 'mức độ', 'muc do', 'độ ưu tiên', 'severity'],
+};
+
+function autoDetectColumnMap(headerRow) {
+  const map = {};
+  headerRow.forEach((cell, idx) => {
+    const normalized = String(cell).toLowerCase().trim();
+    if (!normalized) return;
+    for (const [field, aliases] of Object.entries(HEADER_ALIASES)) {
+      if (!map[field] && aliases.some(a => normalized.includes(a))) {
+        // Convert 0-based index to Excel letter (A=0, B=1, ...)
+        let col = '';
+        let n = idx;
+        do { col = String.fromCharCode(65 + (n % 26)) + col; n = Math.floor(n / 26) - 1; } while (n >= 0);
+        map[field] = col;
+      }
+    }
+  });
+  return map;
 }
 
 // ─── Common row → ticket mapper ───────────────────────────────────────────────
 
-function parseRowsWithColumnMap(values, colMap) {
+function parseRowsWithColumnMap(values, colMap, channelId) {
+  // Find first non-empty row to use as auto-detect source if needed
+  const firstNonEmpty = values.find(r => r.some(c => c !== ''));
+
+  // Auto-detect or fall back to raw if still missing
+  const resolvedMap = (colMap && Object.keys(colMap).length > 0)
+    ? colMap
+    : (firstNonEmpty ? autoDetectColumnMap(firstNonEmpty) : {});
+
+  if (!colMap || Object.keys(colMap).length === 0) {
+    process.stderr.write(
+      `[vp-intake] No column_map configured. Auto-detected: ${JSON.stringify(resolvedMap)}. ` +
+      `Header row: ${JSON.stringify(firstNonEmpty || [])}\n`
+    );
+  }
+
   const tickets = [];
+  // Skip header row(s): if auto-detected, skip until first row that has a non-header value
+  const startRow = (colMap && Object.keys(colMap).length > 0) ? 1 : values.findIndex(r => r.some(c => c !== '')) + 1;
 
-  for (let i = 1; i < values.length; i++) {
+  for (let i = startRow; i < values.length; i++) {
     const row = values[i];
     const get = (field) => {
-      const col = colMap[field];
+      const col = resolvedMap[field];
       if (!col) return '';
       const idx = colLetterToIndex(col);
       return row[idx] !== undefined ? String(row[idx]) : '';
@@ -279,7 +362,7 @@ function parseRowsWithColumnMap(values, colMap) {
       date:        get('date'),
       status:      get('status'),
       _source_row: i,
-      _channel_id: channel ? channel.id : undefined,
+      _channel_id: channelId,
     };
 
     if (!ticket.title && !ticket.description) continue;
@@ -325,4 +408,6 @@ module.exports = {
   isSharingLink,
   resolveSharePointDownloadUrl,
   parseXlsxBuffer,
+  autoDetectColumnMap,
+  HEADER_ALIASES,
 };

package/lib/intake/auto-intake.cjs

@@ -0,0 +1,194 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const { classifyTicket }  = require('./classifier.cjs');
+const { createRequestFile: _createRequestFile, nextRequestNumber } = require('./triage-ux.cjs');
+
+// Internal helper — wraps triage-ux createRequestFile which isn't exported,
+// so we re-implement the minimal version needed for headless auto-accept.
+function createRequestFile(ticket, type, channel, projectRoot) {
+  const n = nextRequestNumber(type, projectRoot);
+  const id = `${type}-${String(n).padStart(3, '0')}`;
+  const now = new Date().toISOString().split('T')[0];
+  const typeLabel = type === 'BUG' ? 'Bug' : 'Enhancement';
+
+  const content = `# ${typeLabel}: ${ticket.title}
+
+## Meta
+- **ID**: ${id}
+- **Type**: ${typeLabel}
+- **Status**: new
+- **Priority**: medium
+- **Created**: ${now}
+- **Reporter**: ${ticket.reporter || 'Auto-intake'}
+- **Source**: ${channel.name} — ticket #${ticket.id}
+- **Assignee**: AI
+
+## Summary
+${ticket.description || ticket.title}
+
+## Acceptance Criteria
+- [ ] (derived from description — fill in before planning)
+`;
+
+  const reqDir = path.join(projectRoot, '.viepilot', 'requests');
+  if (!fs.existsSync(reqDir)) fs.mkdirSync(reqDir, { recursive: true });
+  const filePath = path.join(reqDir, `${id}.md`);
+  fs.writeFileSync(filePath, content, 'utf8');
+  return { id, filePath };
+}
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const CONFIDENCE_THRESHOLD = 0.7;
+
+// ─── Pending-review accumulation ─────────────────────────────────────────────
+
+async function appendPendingReview(tickets, channel, pendingPath) {
+  const filePath = pendingPath || path.join('.viepilot', 'intake', 'pending-review.json');
+  const existing = fs.existsSync(filePath)
+    ? JSON.parse(fs.readFileSync(filePath, 'utf8'))
+    : { items: [] };
+
+  existing.items.push(
+    ...tickets.map((t) => ({
+      ...t,
+      channel: channel.name,
+      queued_at: new Date().toISOString(),
+    })),
+  );
+
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(existing, null, 2));
+}
+
+// ─── Triage report ────────────────────────────────────────────────────────────
+
+async function writeTriageReport({ accepted, queued, channel, projectRoot }) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const reportDir = path.join(projectRoot, '.viepilot', 'intake');
+  if (!fs.existsSync(reportDir)) fs.mkdirSync(reportDir, { recursive: true });
+  const reportPath = path.join(reportDir, `TRIAGE-auto-${timestamp}.md`);
+
+  const lines = [
+    `# Auto-Intake Triage Report`,
+    ``,
+    `**Channel**: ${channel.name}`,
+    `**Date**: ${new Date().toISOString().split('T')[0]}`,
+    `**Mode**: auto (scheduled)`,
+    ``,
+    `## Auto-accepted (confidence ≥ ${CONFIDENCE_THRESHOLD})`,
+    ``,
+    ...accepted.map((t) => `- **${t.request_id}**: ${t.ticket.title} (confidence: ${(t.ticket._confidence || 0).toFixed(2)})`),
+    ``,
+    `## Queued for review (confidence < ${CONFIDENCE_THRESHOLD})`,
+    ``,
+    ...queued.map((t) => `- #${t.id || t._source_row}: ${t.title} (confidence: ${(t._confidence || 0).toFixed(2)})`),
+  ];
+
+  fs.writeFileSync(reportPath, lines.join('\n'), 'utf8');
+  return reportPath;
+}
+
+// ─── Schedule management ──────────────────────────────────────────────────────
+
+function readSchedule(projectRoot) {
+  const filePath = path.join(projectRoot || '.', '.viepilot', 'intake', 'schedule.json');
+  if (!fs.existsSync(filePath)) return null;
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+async function createSchedule(cronExpression, channelId, projectRoot) {
+  const root = projectRoot || '.';
+  // CronCreate is a deferred tool — the invoking agent must call
+  // ToolSearch("select:CronCreate") before using it.
+  // Non-CC fallback: print guidance.
+  const isClaudeCode = process.env.CLAUDE_CODE === '1' || process.env.VP_ADAPTER === 'claude-code';
+
+  if (!isClaudeCode) {
+    console.log('Scheduling requires Claude Code. Use cron + CLI instead.');
+    console.log(`Suggested: cron "${cronExpression} claude /vp-intake --channel ${channelId} --auto"`);
+    return { success: false, error: 'Not running in Claude Code context' };
+  }
+
+  // In CC context, the caller (SKILL.md) must invoke CronCreate via ToolSearch.
+  // This function writes schedule.json after receiving the schedule_id from CronCreate.
+  const scheduleData = {
+    cron: cronExpression,
+    schedule_id: null,   // filled by caller after CronCreate response
+    channel_id: channelId,
+    created: new Date().toISOString(),
+  };
+
+  const scheduleDir = path.join(root, '.viepilot', 'intake');
+  if (!fs.existsSync(scheduleDir)) fs.mkdirSync(scheduleDir, { recursive: true });
+  fs.writeFileSync(path.join(scheduleDir, 'schedule.json'), JSON.stringify(scheduleData, null, 2));
+  return { success: true, scheduleData };
+}
+
+async function deleteSchedule(projectRoot) {
+  const root = projectRoot || '.';
+  const filePath = path.join(root, '.viepilot', 'intake', 'schedule.json');
+  if (!fs.existsSync(filePath)) {
+    return { success: false, error: 'No schedule found — nothing to delete' };
+  }
+  const { schedule_id } = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  // Caller must invoke CronDelete({ schedule_id }) via ToolSearch("select:CronDelete")
+  fs.unlinkSync(filePath);
+  return { success: true, schedule_id };
+}
+
+// ─── Main auto-intake runner ──────────────────────────────────────────────────
+
+async function runAutoIntake(tickets, channel, options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+
+  // 1. Classify with confidence
+  const classified = tickets.map((t) => {
+    const { classified: cls, confidence } = classifyTicket(t);
+    return { ...t, _classified: cls, _confidence: confidence };
+  });
+
+  // 2. Partition: accepted (≥ threshold) vs. queued (< threshold)
+  const accepted = classified.filter((t) => t._confidence >= CONFIDENCE_THRESHOLD && t._classified !== 'UNCLEAR');
+  const queued   = classified.filter((t) => t._confidence <  CONFIDENCE_THRESHOLD || t._classified === 'UNCLEAR');
+
+  // 3. Auto-create request files for accepted tickets
+  const acceptedWithIds = [];
+  for (const t of accepted) {
+    const { id } = createRequestFile(t, t._classified, channel, projectRoot);
+    acceptedWithIds.push({ ticket: t, request_id: id });
+  }
+
+  // 4. Append queued tickets to pending-review.json
+  if (queued.length > 0) {
+    await appendPendingReview(queued, channel);
+  }
+
+  // 5. Write triage report
+  const reportPath = await writeTriageReport({ accepted: acceptedWithIds, queued, channel, projectRoot });
+
+  // 6. Print auto-run summary
+  console.log(`[AUTO INTAKE] Channel: ${channel.name} | ${tickets.length} tickets classified`);
+  if (acceptedWithIds.length > 0) {
+    console.log(`Auto-accepted (${acceptedWithIds.length}): ${acceptedWithIds.map((a) => a.request_id).join(', ')} (confidence ≥ ${CONFIDENCE_THRESHOLD})`);
+  }
+  if (queued.length > 0) {
+    console.log(`Queued for review (${queued.length}): ${queued.map((t) => `${t.id || t._source_row} (confidence ${(t._confidence || 0).toFixed(2)})`).join(', ')}`);
+  }
+  console.log(`Report: ${reportPath}`);
+
+  return { accepted: acceptedWithIds, queued, reportPath };
+}
+
+module.exports = {
+  runAutoIntake,
+  appendPendingReview,
+  createSchedule,
+  deleteSchedule,
+  readSchedule,
+  CONFIDENCE_THRESHOLD,
+};

package/lib/intake/channels.cjs

@@ -93,8 +93,8 @@ function validateChannel(channel) {
   if (channel.type === 'google_sheets' && !channel.spreadsheet_id) {
     throw new Error(`Google Sheets channel "${channel.id}" must have a "spreadsheet_id" field`);
   }
-  if (channel.type === 'excel_m365' && !channel.workbook_id) {
-    throw new Error(`Excel/M365 channel "${channel.id}" must have a "workbook_id" field`);
+  if (channel.type === 'excel_m365' && !channel.workbook_id && !channel.sharing_url) {
+    throw new Error(`Excel/M365 channel "${channel.id}" must have "workbook_id" or "sharing_url"`);
   }
   return true;
 }
@@ -136,4 +136,45 @@ function initIntakeDir(projectRoot) {
   return { intakeDir, channelsPath, credentialsDir };
 }
 
-module.exports = { loadChannels, validateChannel, getChannelById, initIntakeDir, CHANNELS_SCAFFOLD };
+/** Returns true if the channel is an unfilled scaffold stub. */
+function isStubChannel(ch) {
+  if (!ch || !ch.id) return true;
+  if (ch.id.endsWith('-example')) return true;
+  return JSON.stringify(ch).includes('REPLACE_WITH_');
+}
+
+/** Returns true if channels array has at least one non-stub channel. */
+function hasRealChannels(channels) {
+  return Array.isArray(channels) && channels.some((ch) => !isStubChannel(ch));
+}
+
+/**
+ * Append a new channel to channels.json.
+ * Strips stub channels; preserves existing non-stub channels.
+ */
+function appendChannel(projectRoot, channelObj) {
+  initIntakeDir(projectRoot);
+  const channelsPath = path.join(projectRoot, CHANNELS_REL);
+  let existing = [];
+  try {
+    const parsed = JSON.parse(fs.readFileSync(channelsPath, 'utf8'));
+    existing = Array.isArray(parsed.channels) ? parsed.channels : [];
+  } catch {
+    existing = [];
+  }
+  const nonStubs = existing.filter((ch) => !isStubChannel(ch));
+  const updated = [...nonStubs, channelObj];
+  fs.writeFileSync(channelsPath, JSON.stringify({ channels: updated }, null, 2) + '\n', 'utf8');
+  return channelObj;
+}
+
+module.exports = {
+  loadChannels,
+  validateChannel,
+  getChannelById,
+  initIntakeDir,
+  CHANNELS_SCAFFOLD,
+  isStubChannel,
+  hasRealChannels,
+  appendChannel,
+};

package/lib/intake/classifier.cjs

@@ -18,15 +18,33 @@ const ENH_KEYWORDS = [
 ];
 
 function classifyTicket(ticket) {
+  const titleWords = (ticket.title || '').trim().split(/\s+/).filter(Boolean);
+  const totalWords = titleWords.length || 1;
   const text = `${ticket.title || ''} ${ticket.description || ''}`.toLowerCase();
 
+  let matchedKeywords = 0;
+  let classified = 'UNCLEAR';
+
   for (const kw of BUG_KEYWORDS) {
-    if (text.includes(kw)) return 'BUG';
+    if (text.includes(kw)) {
+      classified = 'BUG';
+      matchedKeywords += titleWords.filter((w) => w.toLowerCase().includes(kw)).length || 1;
+      break;
+    }
   }
-  for (const kw of ENH_KEYWORDS) {
-    if (text.includes(kw)) return 'ENH';
+
+  if (classified === 'UNCLEAR') {
+    for (const kw of ENH_KEYWORDS) {
+      if (text.includes(kw)) {
+        classified = 'ENH';
+        matchedKeywords += titleWords.filter((w) => w.toLowerCase().includes(kw)).length || 1;
+        break;
+      }
+    }
   }
-  return 'UNCLEAR';
+
+  const confidence = classified === 'UNCLEAR' ? 0.0 : Math.min(matchedKeywords / totalWords, 1.0);
+  return { classified, confidence };
 }
 
 module.exports = { classifyTicket };

package/lib/intake/manifest.cjs

@@ -0,0 +1,81 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const DEFAULT_TTL_DAYS = 7;
+const MANIFEST_DIR_REL = path.join('.viepilot', 'intake');
+
+function slugify(str) {
+  return String(str)
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/[\s_]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function manifestPath(channelId, projectRoot) {
+  const root = projectRoot || process.cwd();
+  return path.join(root, MANIFEST_DIR_REL, `${slugify(channelId)}-manifest.json`);
+}
+
+function saveManifest(channelId, manifest, projectRoot) {
+  const root = projectRoot || process.cwd();
+  const dir  = path.join(root, MANIFEST_DIR_REL);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const data = {
+    ...manifest,
+    channel_id: slugify(channelId),
+    saved_at:   new Date().toISOString(),
+  };
+  fs.writeFileSync(manifestPath(channelId, root), JSON.stringify(data, null, 2), 'utf8');
+}
+
+function loadManifest(channelId, projectRoot) {
+  const p = manifestPath(channelId, projectRoot);
+  if (!fs.existsSync(p)) return null;
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function isManifestFresh(manifest, ttlDays) {
+  if (!manifest) return false;
+  const days   = typeof ttlDays === 'number' ? ttlDays : DEFAULT_TTL_DAYS;
+  const ts     = manifest.analyzed_at || manifest.saved_at;
+  if (!ts) return false;
+  const ageMs  = Date.now() - new Date(ts).getTime();
+  return ageMs < days * 86400000;
+}
+
+function getColumnMap(manifest, sheetName) {
+  if (!manifest || !Array.isArray(manifest.sheets)) return null;
+  const sheet = sheetName
+    ? manifest.sheets.find((s) => s.name === sheetName)
+    : manifest.sheets[0];
+  if (!sheet || !sheet.columns) return null;
+  const map = {};
+  for (const [col, def] of Object.entries(sheet.columns)) {
+    if (def && def.field) map[def.field] = col;
+  }
+  return Object.keys(map).length ? map : {};
+}
+
+function getWriteBackConfig(manifest, sheetName) {
+  if (!manifest || !Array.isArray(manifest.sheets)) return null;
+  const sheet = sheetName
+    ? manifest.sheets.find((s) => s.name === sheetName)
+    : manifest.sheets[0];
+  if (!sheet || !sheet.write_back) return null;
+  return sheet.write_back;
+}
+
+module.exports = {
+  saveManifest,
+  loadManifest,
+  isManifestFresh,
+  getColumnMap,
+  getWriteBackConfig,
+  manifestPath,
+  slugify,
+  DEFAULT_TTL_DAYS,
+};