task-summary-extractor 8.1.0

package/src/utils/global-config.js

@@ -0,0 +1,315 @@
+/**
+ * Global configuration manager — persistent config stored in ~/.taskexrc
+ *
+ * Resolution priority (highest wins):
+ *   1. CLI flags (--gemini-key, --firebase-key, etc.)
+ *   2. process.env (set by user shell or CI)
+ *   3. CWD .env file (project-specific)
+ *   4. ~/.taskexrc (global persistent config)
+ *   5. Package root .env (development fallback)
+ *
+ * The global config is a JSON file at ~/.taskexrc containing:
+ *   { "GEMINI_API_KEY": "...", "FIREBASE_API_KEY": "...", ... }
+ *
+ * Use `taskex config` to interactively set/update keys.
+ * Use `taskex config --show` to display current saved config.
+ * Use `taskex config --clear` to remove the global config file.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ── Config file path ──────────────────────────────────────────────────────
+const CONFIG_FILE = path.join(os.homedir(), '.taskexrc');
+
+// ── Known config keys ─────────────────────────────────────────────────────
+// Maps config key name → description (for interactive prompts)
+const CONFIG_KEYS = {
+  GEMINI_API_KEY:          { label: 'Gemini API Key',          required: true,  hint: 'Get one at https://aistudio.google.com/apikey' },
+  GEMINI_MODEL:            { label: 'Default Gemini Model',    required: false, hint: 'e.g. gemini-2.5-flash, gemini-2.5-pro' },
+  FIREBASE_API_KEY:        { label: 'Firebase API Key',        required: false, hint: 'From Firebase Console → Project Settings' },
+  FIREBASE_PROJECT_ID:     { label: 'Firebase Project ID',     required: false, hint: 'e.g. my-project-12345' },
+  FIREBASE_STORAGE_BUCKET: { label: 'Firebase Storage Bucket', required: false, hint: 'e.g. my-project-12345.appspot.com' },
+  FIREBASE_AUTH_DOMAIN:    { label: 'Firebase Auth Domain',    required: false, hint: 'e.g. my-project-12345.firebaseapp.com' },
+};
+
+// ── Read / Write ──────────────────────────────────────────────────────────
+
+/**
+ * Load the global config from ~/.taskexrc.
+ * Returns an object of key-value pairs, or {} if file doesn't exist.
+ * @returns {Record<string, string>}
+ */
+function loadGlobalConfig() {
+  try {
+    if (!fs.existsSync(CONFIG_FILE)) return {};
+    const raw = fs.readFileSync(CONFIG_FILE, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return {};
+    return parsed;
+  } catch (err) {
+    // Warn if file exists but is corrupt (not just missing)
+    if (fs.existsSync(CONFIG_FILE)) {
+      process.stderr.write(`  ⚠ Could not parse ${CONFIG_FILE}: ${err.message}\n`);
+      process.stderr.write(`    Run \`taskex config\` to reconfigure, or delete the file.\n`);
+    }
+    return {};
+  }
+}
+
+/**
+ * Save the global config to ~/.taskexrc.
+ * Merges new values into existing config (doesn't overwrite unrelated keys).
+ * @param {Record<string, string>} newValues
+ */
+function saveGlobalConfig(newValues) {
+  const existing = loadGlobalConfig();
+  const merged = { ...existing, ...newValues };
+
+  // Remove empty/null values
+  for (const key of Object.keys(merged)) {
+    if (!merged[key]) delete merged[key];
+  }
+
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+  // Restrict permissions on config file (contains secrets)
+  try {
+    if (process.platform !== 'win32') {
+      fs.chmodSync(CONFIG_FILE, 0o600);
+    }
+  } catch {
+    // Best-effort — Windows doesn't support chmod
+  }
+}
+
+/**
+ * Delete the global config file.
+ * @returns {boolean} true if file was deleted
+ */
+function clearGlobalConfig() {
+  try {
+    if (fs.existsSync(CONFIG_FILE)) {
+      fs.unlinkSync(CONFIG_FILE);
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+// ── Inject into process.env ───────────────────────────────────────────────
+
+/**
+ * Load global config and inject any values into process.env that aren't
+ * already set. This respects the priority chain: env vars / CLI flags
+ * that are already set take precedence over global config.
+ *
+ * Call this BEFORE dotenv loads (so it's lower priority than .env too — 
+ * actually call it AFTER dotenv, but only inject if still missing).
+ *
+ * @returns {string[]} List of keys that were injected from global config
+ */
+function injectGlobalConfig() {
+  const config = loadGlobalConfig();
+  const injected = [];
+
+  for (const [key, value] of Object.entries(config)) {
+    if (value && (!process.env[key] || process.env[key] === '')) {
+      process.env[key] = value;
+      injected.push(key);
+    }
+  }
+
+  return injected;
+}
+
+// ── Interactive setup ─────────────────────────────────────────────────────
+
+/**
+ * Mask a secret for display — shows first 4 + last 4 chars.
+ * @param {string} value
+ * @returns {string}
+ */
+function maskSecret(value) {
+  if (!value || value.length < 12) return '****';
+  return value.slice(0, 4) + '...' + value.slice(-4);
+}
+
+/**
+ * Interactive config setup — prompts for each key and saves to ~/.taskexrc.
+ * Shows current values (masked) and lets user update or keep existing.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.showOnly=false]    Just display, don't prompt
+ * @param {boolean} [options.clear=false]       Delete config file
+ * @param {boolean} [options.onlyMissing=false] Only prompt for keys not yet set anywhere
+ * @returns {Promise<void>}
+ */
+async function interactiveSetup({ showOnly = false, clear = false, onlyMissing = false } = {}) {
+  const readline = require('readline');
+
+  if (clear) {
+    const removed = clearGlobalConfig();
+    if (removed) {
+      console.log('\n  ✓ Global config cleared (~/.taskexrc deleted)\n');
+    } else {
+      console.log('\n  No global config to clear.\n');
+    }
+    return;
+  }
+
+  const existing = loadGlobalConfig();
+
+  if (showOnly) {
+    console.log('');
+    console.log('  Global Config (~/.taskexrc)');
+    console.log('  ─────────────────────────────');
+
+    const keys = Object.keys(CONFIG_KEYS);
+    let hasAny = false;
+    for (const key of keys) {
+      const val = existing[key] || process.env[key];
+      const source = existing[key] ? 'saved' : process.env[key] ? 'env' : '';
+      if (val) {
+        const display = key.includes('KEY') || key.includes('SECRET') ? maskSecret(val) : val;
+        console.log(`    ${CONFIG_KEYS[key].label}: ${display}  (${source})`);
+        hasAny = true;
+      }
+    }
+    if (!hasAny) {
+      console.log('    (empty — run `taskex config` to set up)');
+    }
+    console.log(`\n  Config file: ${CONFIG_FILE}\n`);
+    return;
+  }
+
+  // Interactive prompts
+  console.log('');
+  console.log('  ┌──────────────────────────────────────────────────────────┐');
+  console.log('  │              🔧  taskex — Global Configuration           │');
+  console.log('  └──────────────────────────────────────────────────────────┘');
+  console.log('');
+  console.log(`  Config file: ${CONFIG_FILE}`);
+  console.log('  Values saved here are used whenever .env or CLI flags don\'t set them.');
+  console.log('  Press Enter to keep the current value, or type a new one.');
+  console.log('');
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (question) => new Promise(resolve => {
+    rl.question(question, answer => resolve((answer || '').trim()));
+  });
+
+  const updates = {};
+
+  try {
+    for (const [key, meta] of Object.entries(CONFIG_KEYS)) {
+      const current = existing[key] || process.env[key] || '';
+
+      // If onlyMissing mode, skip keys that are already set
+      if (onlyMissing && current) continue;
+
+      const displayCurrent = current
+        ? (key.includes('KEY') || key.includes('SECRET') ? maskSecret(current) : current)
+        : '(not set)';
+
+      const reqTag = meta.required ? ' *required*' : '';
+      console.log(`  ${meta.label}${reqTag}`);
+      if (meta.hint) console.log(`    ${meta.hint}`);
+      console.log(`    Current: ${displayCurrent}`);
+
+      const answer = await ask('    New value (Enter to keep): ');
+      if (answer) {
+        updates[key] = answer;
+      }
+      console.log('');
+    }
+  } finally {
+    rl.close();
+  }
+
+  if (Object.keys(updates).length > 0) {
+    saveGlobalConfig(updates);
+    console.log(`  ✓ Saved ${Object.keys(updates).length} value(s) to ${CONFIG_FILE}`);
+    console.log('');
+
+    // Also inject into current process so the pipeline can proceed
+    for (const [k, v] of Object.entries(updates)) {
+      process.env[k] = v;
+    }
+  } else {
+    console.log('  No changes made.');
+    console.log('');
+  }
+}
+
+/**
+ * Quick prompt for a single missing required key.
+ * Used during first-run when GEMINI_API_KEY is missing after all resolution.
+ *
+ * @param {string} key - The config key (e.g. 'GEMINI_API_KEY')
+ * @returns {Promise<string|null>} The value entered, or null if skipped
+ */
+async function promptForKey(key) {
+  const meta = CONFIG_KEYS[key];
+  if (!meta) return null;
+
+  const readline = require('readline');
+
+  console.log('');
+  console.log(`  ⚠ ${meta.label} is not configured.`);
+  if (meta.hint) console.log(`    ${meta.hint}`);
+  console.log('');
+
+  let value;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    value = await new Promise(resolve => {
+      rl.question(`  Enter ${meta.label}: `, answer => resolve((answer || '').trim()));
+    });
+  } finally {
+    rl.close();
+  }
+
+  if (!value) return null;
+
+  // Ask if they want to save globally
+  let save;
+  const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    save = await new Promise(resolve => {
+      rl2.question('  Save to global config for future use? (Y/n): ', answer => {
+        const a = (answer || '').trim().toLowerCase();
+        resolve(a === '' || a === 'y' || a === 'yes');
+      });
+    });
+  } finally {
+    rl2.close();
+  }
+
+  if (save) {
+    saveGlobalConfig({ [key]: value });
+    console.log(`  ✓ Saved to ${CONFIG_FILE}`);
+  }
+
+  // Inject into current process
+  process.env[key] = value;
+  return value;
+}
+
+// ── Exports ───────────────────────────────────────────────────────────────
+
+module.exports = {
+  CONFIG_FILE,
+  CONFIG_KEYS,
+  loadGlobalConfig,
+  saveGlobalConfig,
+  clearGlobalConfig,
+  injectGlobalConfig,
+  interactiveSetup,
+  promptForKey,
+  maskSecret,
+};

package/src/utils/health-dashboard.js

@@ -0,0 +1,216 @@
+/**
+ * Pipeline Health Dashboard — generates a comprehensive quality report
+ * after all processing is complete.
+ *
+ * Reports on:
+ *  - Parse success rates
+ *  - Quality scores per segment
+ *  - Extraction density (items per segment)
+ *  - Data coverage analysis
+ *  - Retry statistics
+ *  - Token efficiency metrics
+ */
+
+'use strict';
+
+// ======================== HEALTH REPORT ========================
+
+/**
+ * Build a comprehensive health report from pipeline execution data.
+ *
+ * @param {object} params
+ * @param {Array} params.segmentReports - Array of { segmentName, qualityReport, retried, retryImproved }
+ * @param {Array} params.allSegmentAnalyses - All final segment analyses
+ * @param {object} params.costSummary - From CostTracker.getSummary()
+ * @param {object} [params.compilationQuality] - Quality report for the compilation step
+ * @param {number} params.totalDurationMs - Wall-clock duration of pipeline
+ * @returns {object} Health report
+ */
+function buildHealthReport(params) {
+  const {
+    segmentReports = [],
+    allSegmentAnalyses = [],
+    costSummary = {},
+    compilationQuality = null,
+    totalDurationMs = 0,
+  } = params;
+
+  // Parse success rate
+  const totalSegments = segmentReports.length;
+  const parsed = segmentReports.filter(r => r.qualityReport?.grade !== 'FAIL').length;
+  const parseRate = totalSegments > 0 ? (parsed / totalSegments * 100).toFixed(1) : 0;
+
+  // Quality score distribution
+  const scores = segmentReports.map(r => r.qualityReport?.score || 0);
+  const avgScore = scores.length > 0 ? (scores.reduce((a, b) => a + b, 0) / scores.length).toFixed(1) : 0;
+  const minScore = scores.length > 0 ? Math.min(...scores) : 0;
+  const maxScore = scores.length > 0 ? Math.max(...scores) : 0;
+
+  // Grade distribution
+  const grades = { PASS: 0, WARN: 0, FAIL: 0 };
+  for (const r of segmentReports) {
+    const g = r.qualityReport?.grade || 'FAIL';
+    grades[g] = (grades[g] || 0) + 1;
+  }
+
+  // Extraction density
+  let totalTickets = 0, totalCrs = 0, totalActions = 0, totalBlockers = 0, totalScopes = 0;
+  const perSegment = [];
+
+  for (const analysis of allSegmentAnalyses) {
+    const tickets = analysis.tickets?.length || 0;
+    const crs = analysis.change_requests?.length || 0;
+    const actions = analysis.action_items?.length || 0;
+    const blockers = analysis.blockers?.length || 0;
+    const scopes = analysis.scope_changes?.length || 0;
+
+    totalTickets += tickets;
+    totalCrs += crs;
+    totalActions += actions;
+    totalBlockers += blockers;
+    totalScopes += scopes;
+
+    perSegment.push({ tickets, crs, actions, blockers, scopes });
+  }
+
+  // Retry stats
+  const retriedCount = segmentReports.filter(r => r.retried).length;
+  const retryImprovedCount = segmentReports.filter(r => r.retryImproved).length;
+
+  // Token efficiency
+  const tokensPerItem = costSummary.totalTokens && (totalTickets + totalCrs + totalActions) > 0
+    ? Math.round(costSummary.totalTokens / (totalTickets + totalCrs + totalActions))
+    : 0;
+
+  // All issues across segments
+  const allIssues = [];
+  for (const r of segmentReports) {
+    for (const issue of (r.qualityReport?.issues || [])) {
+      allIssues.push({ segment: r.segmentName, issue });
+    }
+  }
+
+  return {
+    summary: {
+      totalSegments,
+      parseSuccessRate: parseFloat(parseRate),
+      avgQualityScore: parseFloat(avgScore),
+      minQualityScore: minScore,
+      maxQualityScore: maxScore,
+      grades,
+    },
+    extraction: {
+      totalTickets,
+      totalChangeRequests: totalCrs,
+      totalActionItems: totalActions,
+      totalBlockers,
+      totalScopeChanges: totalScopes,
+      totalItems: totalTickets + totalCrs + totalActions + totalBlockers + totalScopes,
+      perSegment,
+    },
+    retry: {
+      segmentsRetried: retriedCount,
+      retriesImproved: retryImprovedCount,
+    },
+    efficiency: {
+      tokensPerExtractedItem: tokensPerItem,
+      totalTokens: costSummary.totalTokens || 0,
+      totalCost: costSummary.totalCost || 0,
+      aiTimeMs: costSummary.totalDurationMs || 0,
+      wallClockMs: totalDurationMs,
+    },
+    compilation: compilationQuality ? {
+      score: compilationQuality.score,
+      grade: compilationQuality.grade,
+      issues: compilationQuality.issues,
+    } : null,
+    issues: allIssues,
+  };
+}
+
+/**
+ * Print the health dashboard to console.
+ * @param {object} report - From buildHealthReport
+ */
+function printHealthDashboard(report) {
+  const { summary: s, extraction: e, retry: r, efficiency: eff, compilation: c } = report;
+
+  console.log('');
+  console.log('╔══════════════════════════════════════════════╗');
+  console.log('║         PIPELINE HEALTH DASHBOARD            ║');
+  console.log('╚══════════════════════════════════════════════╝');
+  console.log('');
+
+  // Quality overview
+  console.log('  Quality Scores:');
+  console.log(`    Average : ${s.avgQualityScore}/100`);
+  console.log(`    Range   : ${s.minQualityScore}–${s.maxQualityScore}`);
+  console.log(`    Grades  : ✓ ${s.grades.PASS} PASS | ⚠ ${s.grades.WARN} WARN | ✗ ${s.grades.FAIL} FAIL`);
+  console.log(`    Parse   : ${s.parseSuccessRate}% success rate`);
+  console.log('');
+
+  // Extraction density
+  console.log('  Extraction Summary:');
+  console.log(`    Tickets         : ${e.totalTickets}`);
+  console.log(`    Change Requests : ${e.totalChangeRequests}`);
+  console.log(`    Action Items    : ${e.totalActionItems}`);
+  console.log(`    Blockers        : ${e.totalBlockers}`);
+  console.log(`    Scope Changes   : ${e.totalScopeChanges}`);
+  console.log(`    Total items     : ${e.totalItems} across ${s.totalSegments} segment(s)`);
+  console.log('');
+
+  // Per-segment density bars
+  if (e.perSegment.length > 0) {
+    console.log('  Per-Segment Density:');
+    e.perSegment.forEach((seg, i) => {
+      const total = seg.tickets + seg.crs + seg.actions + seg.blockers + seg.scopes;
+      const bar = '█'.repeat(Math.min(total, 30)) + (total > 30 ? '…' : '');
+      console.log(`    Seg ${i + 1}: ${bar} (${total} items)`);
+    });
+    console.log('');
+  }
+
+  // Retry stats
+  if (r.segmentsRetried > 0) {
+    console.log('  Retry Statistics:');
+    console.log(`    Segments retried : ${r.segmentsRetried}`);
+    console.log(`    Retries improved : ${r.retriesImproved}`);
+    console.log('');
+  }
+
+  // Efficiency
+  console.log('  Efficiency:');
+  console.log(`    Tokens/item : ${eff.tokensPerExtractedItem.toLocaleString()}`);
+  console.log(`    AI time     : ${(eff.aiTimeMs / 1000).toFixed(1)}s`);
+  console.log(`    Wall clock  : ${(eff.wallClockMs / 1000).toFixed(1)}s`);
+  console.log(`    Cost        : $${eff.totalCost.toFixed(4)}`);
+
+  // Compilation quality
+  if (c) {
+    console.log('');
+    console.log('  Compilation:');
+    console.log(`    Score : ${c.score}/100 (${c.grade})`);
+    if (c.issues.length > 0) {
+      console.log(`    Issues: ${c.issues.length}`);
+      c.issues.slice(0, 3).forEach(issue => console.log(`      • ${issue}`));
+      if (c.issues.length > 3) console.log(`      ... +${c.issues.length - 3} more`);
+    }
+  }
+
+  // Top issues
+  const criticalIssues = report.issues.filter(i =>
+    i.issue.includes('FAIL') || i.issue.includes('Missing required') || i.issue.includes('parse failed')
+  );
+  if (criticalIssues.length > 0) {
+    console.log('');
+    console.log('  ⚠ Critical Issues:');
+    criticalIssues.slice(0, 5).forEach(i => console.log(`    ${i.segment}: ${i.issue}`));
+  }
+
+  console.log('');
+}
+
+module.exports = {
+  buildHealthReport,
+  printHealthDashboard,
+};

package/src/utils/inject-cli-flags.js

@@ -0,0 +1,58 @@
+/**
+ * CLI config flag injection — maps --flag values to process.env before
+ * any module touches config.js / dotenv.
+ *
+ * Shared between bin/taskex.js and process_and_upload.js to avoid
+ * duplicated flag-parsing logic.
+ */
+
+'use strict';
+
+/** Map of CLI flag names → environment variable names */
+const CONFIG_FLAG_MAP = {
+  'gemini-key':        'GEMINI_API_KEY',
+  'firebase-key':      'FIREBASE_API_KEY',
+  'firebase-project':  'FIREBASE_PROJECT_ID',
+  'firebase-bucket':   'FIREBASE_STORAGE_BUCKET',
+  'firebase-domain':   'FIREBASE_AUTH_DOMAIN',
+};
+
+/**
+ * Scan process.argv for config flags and inject their values into process.env.
+ * Must be called BEFORE any require() that touches config.js / dotenv.
+ *
+ * Supports both `--key value` and `--key=value` forms.
+ *
+ * @param {string[]} [argv] - Arguments (defaults to process.argv.slice(2))
+ * @returns {string[]} List of env var names that were injected
+ */
+function injectCliFlags(argv) {
+  if (!argv) argv = process.argv.slice(2);
+  const injected = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    if (!argv[i].startsWith('--')) continue;
+
+    const eqIdx = argv[i].indexOf('=');
+    let key, val;
+
+    if (eqIdx !== -1) {
+      key = argv[i].slice(2, eqIdx);
+      val = argv[i].slice(eqIdx + 1);
+    } else {
+      key = argv[i].slice(2);
+      if (CONFIG_FLAG_MAP[key] && i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+        val = argv[i + 1];
+      }
+    }
+
+    if (key && val && CONFIG_FLAG_MAP[key]) {
+      process.env[CONFIG_FLAG_MAP[key]] = val;
+      injected.push(CONFIG_FLAG_MAP[key]);
+    }
+  }
+
+  return injected;
+}
+
+module.exports = { injectCliFlags, CONFIG_FLAG_MAP };