@craftpipe/contextpack 1.0.0

package/lib/premium/index.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const { checkPro, requirePro } = require('./lib/premium/gate');
+const htmlReport = require('./lib/premium/html-report');
+const watchMode = require('./lib/premium/watch-mode');
+const configFile = require('./lib/premium/config-file');
+
+const premiumFeatures = {
+  'html-report': htmlReport,
+  'watch-mode': watchMode,
+  'config-file': configFile,
+};
+
+function addPremiumCommands(program) {
+  program
+    .option(
+      '--html-report [outputPath]',
+      '[PRO] Generate an HTML report of the results'
+    )
+    .option(
+      '--watch',
+      '[PRO] Watch for file changes and re-run automatically'
+    )
+    .option(
+      '--config <configPath>',
+      '[PRO] Load options from a configuration file'
+    );
+
+  return program;
+}
+
+function runPremium(feature, data) {
+  requirePro(feature);
+
+  const mod = premiumFeatures[feature];
+
+  if (!mod) {
+    throw new Error(
+      `Unknown premium feature: "${feature}". ` +
+      `Available features: ${Object.keys(premiumFeatures).join(', ')}`
+    );
+  }
+
+  if (typeof mod.run !== 'function') {
+    throw new Error(
+      `Premium feature "${feature}" does not export a run() function.`
+    );
+  }
+
+  return mod.run(data);
+}
+
+module.exports = {
+  addPremiumCommands,
+  runPremium,
+  checkPro,
+};

package/lib/premium/watch-mode.js

@@ -0,0 +1,627 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { requirePro } = require('../premium/gate');
+const { scanProject } = require('../scanner');
+const { analyzeProject } = require('../analyzer');
+const { createBundle, formatAsJSON, formatAsMarkdown } = require('../bundler');
+const { validateBundle } = require('../validator');
+const { calculateBundleSize } = require('../tokenizer');
+const { loadConfig, mergeWithFlags } = require('../config');
+
+/**
+ * Debounce a function call
+ * @param {Function} fn
+ * @param {number} delay
+ * @returns {Function}
+ */
+function debounce(fn, delay) {
+  let timer = null;
+  return function (...args) {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      fn.apply(this, args);
+    }, delay);
+  };
+}
+
+/**
+ * Format bytes into a human-readable string
+ * @param {number} bytes
+ * @returns {string}
+ */
+function formatBytes(bytes) {
+  if (typeof bytes !== 'number' || isNaN(bytes)) return '0 B';
+  if (bytes < 1024) return bytes + ' B';
+  if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + ' KB';
+  return (bytes / (1024 * 1024)).toFixed(2) + ' MB';
+}
+
+/**
+ * Format a duration in milliseconds to a readable string
+ * @param {number} ms
+ * @returns {string}
+ */
+function formatDuration(ms) {
+  if (typeof ms !== 'number' || isNaN(ms)) return '0ms';
+  if (ms < 1000) return ms + 'ms';
+  return (ms / 1000).toFixed(2) + 's';
+}
+
+/**
+ * Get a timestamp string for console output
+ * @returns {string}
+ */
+function timestamp() {
+  const now = new Date();
+  const h = String(now.getHours()).padStart(2, '0');
+  const m = String(now.getMinutes()).padStart(2, '0');
+  const s = String(now.getSeconds()).padStart(2, '0');
+  return '[' + h + ':' + m + ':' + s + ']';
+}
+
+/**
+ * Collect all watchable directories and files from a file list
+ * @param {string[]} filePaths
+ * @param {string} rootDir
+ * @returns {Set<string>}
+ */
+function collectWatchTargets(filePaths, rootDir) {
+  const targets = new Set();
+  const root = path.resolve(rootDir || '.');
+  targets.add(root);
+
+  if (!Array.isArray(filePaths)) return targets;
+
+  for (const filePath of filePaths) {
+    try {
+      const abs = path.resolve(filePath);
+      targets.add(abs);
+      const dir = path.dirname(abs);
+      if (dir !== root) {
+        targets.add(dir);
+      }
+    } catch (_) {
+      // skip unresolvable paths
+    }
+  }
+
+  return targets;
+}
+
+/**
+ * Resolve the output file path from config and flags
+ * @param {object} config
+ * @returns {string}
+ */
+function resolveOutputPath(config) {
+  const cfg = config || {};
+  const output = cfg.output || 'contextpack-output.json';
+  const format = (cfg.format || 'json').toLowerCase();
+  const ext = path.extname(output);
+  if (!ext) {
+    return output + '.' + format;
+  }
+  return output;
+}
+
+/**
+ * Run the full scan → analyze → bundle → validate pipeline once
+ * @param {object} config - Merged config object
+ * @param {object} watchState - Mutable state shared across runs
+ * @returns {Promise<object>} Result summary
+ */
+async function runPipeline(config, watchState) {
+  const cfg = config || {};
+  const state = watchState || {};
+  const startTime = Date.now();
+  const rootDir = cfg.rootDir || '.';
+  const format = (cfg.format || 'json').toLowerCase();
+  const outputPath = resolveOutputPath(cfg);
+  const verbose = !!cfg.verbose;
+
+  try {
+    if (verbose) {
+      console.log(timestamp() + ' \u{1F50D} Scanning ' + rootDir + ' ...');
+    }
+
+    const scanResult = await scanProject(cfg);
+
+    if (!scanResult || !scanResult.files) {
+      throw new Error('Scanner returned no file data');
+    }
+
+    const filePaths = scanResult.files.map(function (f) {
+      return f && (f.absolutePath || f.path);
+    }).filter(Boolean);
+
+    if (verbose) {
+      console.log(timestamp() + ' \u{1F9E0} Analyzing ' + filePaths.length + ' file(s)...');
+    }
+
+    const analysisResult = await analyzeProject(filePaths, cfg);
+
+    if (verbose) {
+      console.log(timestamp() + ' \u{1F4E6} Bundling...');
+    }
+
+    const bundle = await createBundle(scanResult, analysisResult, cfg);
+
+    if (!bundle) {
+      throw new Error('Bundler returned empty bundle');
+    }
+
+    const validationReport = await validateBundle(bundle, cfg);
+    const tokenInfo = calculateBundleSize(bundle);
+
+    let outputContent;
+    if (format === 'markdown' || format === 'md') {
+      outputContent = formatAsMarkdown(bundle);
+    } else {
+      outputContent = formatAsJSON(bundle);
+    }
+
+    const outputDir = path.dirname(path.resolve(outputPath));
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    fs.writeFileSync(outputPath, outputContent, 'utf8');
+
+    const duration = Date.now() - startTime;
+    const outputSize = Buffer.byteLength(outputContent, 'utf8');
+
+    const hasErrors = validationReport &&
+      Array.isArray(validationReport.errors) &&
+      validationReport.errors.length > 0;
+
+    const hasWarnings = validationReport &&
+      Array.isArray(validationReport.warnings) &&
+      validationReport.warnings.length > 0;
+
+    state.runCount = (state.runCount || 0) + 1;
+    state.lastRunAt = new Date().toISOString();
+    state.lastDuration = duration;
+    state.lastOutputSize = outputSize;
+    state.lastTokenCount = tokenInfo && tokenInfo.totalTokens;
+    state.lastFilesScanned = filePaths.length;
+
+    const statusIcon = hasErrors ? '\u274C' : hasWarnings ? '\u26A0\uFE0F' : '\u2705';
+
+    console.log(
+      timestamp() +
+      ' ' + statusIcon +
+      ' Bundle #' + state.runCount +
+      ' \u2192 ' + outputPath +
+      ' | ' + filePaths.length + ' files' +
+      ' | ~' + (tokenInfo && tokenInfo.totalTokens ? tokenInfo.totalTokens.toLocaleString() : '?') + ' tokens' +
+      ' | ' + formatBytes(outputSize) +
+      ' | ' + formatDuration(duration)
+    );
+
+    if (hasErrors) {
+      console.log(timestamp() + ' \u274C Validation errors:');
+      validationReport.errors.forEach(function (e) {
+        console.log('    - ' + (e && (e.message || e)));
+      });
+    }
+
+    if (hasWarnings && verbose) {
+      console.log(timestamp() + ' \u26A0\uFE0F  Validation warnings:');
+      validationReport.warnings.forEach(function (w) {
+        console.log('    - ' + (w && (w.message || w)));
+      });
+    }
+
+    return {
+      success: true,
+      runCount: state.runCount,
+      filePaths,
+      outputPath,
+      outputSize,
+      duration,
+      tokenInfo,
+      validationReport,
+      hasErrors,
+      hasWarnings,
+    };
+  } catch (err) {
+    const duration = Date.now() - startTime;
+    state.errorCount = (state.errorCount || 0) + 1;
+    console.error(timestamp() + ' \u{1F525} Pipeline error after ' + formatDuration(duration) + ': ' + (err && err.message || String(err)));
+    if (cfg.verbose && err && err.stack) {
+      console.error(err.stack);
+    }
+    return {
+      success: false,
+      error: err,
+      duration,
+    };
+  }
+}
+
+/**
+ * Build the set of fs.watch handles for a list of targets
+ * @param {Set<string>} targets
+ * @param {Function} onChange
+ * @param {object} opts
+ * @returns {Map<string, fs.FSWatcher>}
+ */
+function attachWatchers(targets, onChange, opts) {
+  const options = opts || {};
+  const watchers = new Map();
+
+  targets.forEach(function (target) {
+    try {
+      if (!fs.existsSync(target)) return;
+
+      const stat = fs.statSync(target);
+      const isDir = stat.isDirectory();
+
+      const watcher = fs.watch(
+        target,
+        { recursive: isDir, persistent: true },
+        function (eventType, filename) {
+          const label = filename
+            ? path.join(target, filename)
+            : target;
+          onChange(eventType, label);
+        }
+      );
+
+      watcher.on('error', function (err) {
+        if (options.verbose) {
+          console.warn(timestamp() + ' \u26A0\uFE0F  Watcher error on ' + target + ': ' + (err && err.message));
+        }
+      });
+
+      watchers.set(target, watcher);
+    } catch (err) {
+      if (options.verbose) {
+        console.warn(timestamp() + ' \u26A0\uFE0F  Could not watch ' + target + ': ' + (err && err.message));
+      }
+    }
+  });
+
+  return watchers;
+}
+
+/**
+ * Close all active fs.watch handles
+ * @param {Map<string, fs.FSWatcher>} watchers
+ */
+function closeWatchers(watchers) {
+  if (!watchers) return;
+  watchers.forEach(function (watcher, target) {
+    try {
+      watcher.close();
+    } catch (_) {
+      // ignore close errors
+    }
+  });
+  watchers.clear();
+}
+
+/**
+ * Refresh watchers after a pipeline run to pick up new files/dirs
+ * @param {Map<string, fs.FSWatcher>} watchers
+ * @param {string[]} filePaths
+ * @param {string} rootDir
+ * @param {Function} onChange
+ * @param {object} opts
+ */
+function refreshWatchers(watchers, filePaths, rootDir, onChange, opts) {
+  const newTargets = collectWatchTargets(filePaths, rootDir);
+  const existingKeys = new Set(watchers.keys());
+
+  // Add watchers for new targets
+  newTargets.forEach(function (target) {
+    if (!existingKeys.has(target)) {
+      try {
+        if (!fs.existsSync(target)) return;
+        const stat = fs.statSync(target);
+        const isDir = stat.isDirectory();
+        const watcher = fs.watch(
+          target,
+          { recursive: isDir, persistent: true },
+          function (eventType, filename) {
+            const label = filename ? path.join(target, filename) : target;
+            onChange(eventType, label);
+          }
+        );
+        watcher.on('error', function () {});
+        watchers.set(target, watcher);
+      } catch (_) {
+        // skip
+      }
+    }
+  });
+
+  // Remove watchers for targets that no longer exist
+  existingKeys.forEach(function (key) {
+    if (!newTargets.has(key)) {
+      try {
+        const w = watchers.get(key);
+        if (w) w.close();
+      } catch (_) {
+        // ignore
+      }
+      watchers.delete(key);
+    }
+  });
+}
+
+/**
+ * Determine if a changed file path should trigger a rebuild
+ * @param {string} changedPath
+ * @param {object} config
+ * @returns {boolean}
+ */
+function shouldRebuild(changedPath, config) {
+  const cfg = config || {};
+  const outputPath = path.resolve(resolveOutputPath(cfg));
+  const absChanged = path.resolve(changedPath || '');
+
+  // Never rebuild because the output file itself changed
+  if (absChanged === outputPath) return false;
+
+  // Skip common noise paths
+  const noisePatterns = [
+    /node_modules/,
+    /\.git[/\\]/,
+    /\.nyc_output/,
+    /coverage[/\\]/,
+    /dist[/\\]/,
+    /build[/\\]/,
+    /\.cache[/\\]/,
+    /tmp[/\\]/,
+    /\.DS_Store$/,
+    /Thumbs\.db$/,
+    /~$/,
+  ];
+
+  for (let i = 0; i < noisePatterns.length; i++) {
+    if (noisePatterns[i].test(absChanged)) return false;
+  }
+
+  return true;
+}
+
+/**
+ * Print the watch-mode startup banner
+ * @param {object} config
+ * @param {object} opts
+ */
+function printBanner(config, opts) {
+  const cfg = config || {};
+  const options = opts || {};
+  const rootDir = cfg.rootDir || '.';
+  const outputPath = resolveOutputPath(cfg);
+  const debounceMs = options.debounceMs || 400;
+
+  console.log('');
+  console.log('  \u{1F4E6} ContextPack \u2014 Watch Mode  \u2B50 PRO');
+  console.log('  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500');
+  console.log('  Root     : ' + path.resolve(rootDir));
+  console.log('  Output   : ' + outputPath);
+  console.log('  Format   : ' + (cfg.format || 'json').toUpperCase());
+  console.log('  Debounce : ' + debounceMs + 'ms');
+  console.log('  Verbose  : ' + (cfg.verbose ? 'yes' : 'no'));
+  console.log('  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500');
+  console.log('  Press Ctrl+C to stop.');
+  console.log('');
+}
+
+/**
+ * Print a summary line when watch mode exits
+ * @param {object} state
+ */
+function printExitSummary(state) {
+  const s = state || {};
+  console.log('');
+  console.log('  \u{1F4CA} Watch Mode Summary');
+  console.log('  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500');
+  console.log('  Total builds : ' + (s.runCount || 0));
+  console.log('  Errors       : ' + (s.errorCount || 0));
+  console.log('  Last output  : ' + (s.lastOutputSize ? formatBytes(s.lastOutputSize) : 'n/a'));
+  console.log('  Last tokens  : ' + (s.lastTokenCount ? s.lastTokenCount.toLocaleString() : 'n/a'));
+  console.log('  Last build   : ' + (s.lastDuration ? formatDuration(s.lastDuration) : 'n/a'));
+  console.log('  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500');
+  console.log('');
+}
+
+/**
+ * Main watch-mode entry point (PRO feature)
+ *
+ * Watches the project for file changes and automatically re-runs the full
+ * scan → analyze → bundle → validate pipeline, writing the output file on
+ * every meaningful change.
+ *
+ * @param {object} opts
+ * @param {object}  [opts.flags]       - CLI flags (override config file values)
+ * @param {number}  [opts.debounceMs]  - Milliseconds to debounce rapid changes (default 400)
+ * @param {boolean} [opts.runOnStart]  - Run pipeline immediately on start (default true)
+ * @param {Function}[opts.onRebuild]   - Optional callback(result) after each rebuild
+ * @param {Function}[opts.onError]     - Optional callback(err) on unhandled errors
+ * @returns {Promise<{ stop: Function, getState: Function }>} Control handle
+ */
+async function watchMode(opts) {
+  requirePro('Watch Mode');
+
+  const {
+    flags,
+    debounceMs,
+    runOnStart,
+    onRebuild,
+    onError,
+  } = opts || {};
+
+  const effectiveDebounce = (typeof debounceMs === 'number' && debounceMs >= 0)
+    ? debounceMs
+    : 400;
+
+  const shouldRunOnStart = runOnStart !== false;
+
+  // Load and merge config
+  let config;
+  try {
+    const rawConfig = loadConfig();
+    config = mergeWithFlags(rawConfig, flags || {});
+  } catch (err) {
+    console.error(timestamp() + ' \u274C Failed to load config: ' + (err && err.message));
+    config = mergeWithFlags({}, flags || {});
+  }
+
+  const rootDir = config.rootDir || '.';
+
+  // Shared mutable state across pipeline runs
+  const watchState = {
+    runCount: 0,
+    errorCount: 0,
+    lastRunAt: null,
+    lastDuration: null,
+    lastOutputSize: null,
+    lastTokenCount: null,
+    lastFilesScanned: null,
+    active: true,
+  };
+
+  // Active fs.watch handles
+  let watchers = new Map();
+
+  // Whether a build is currently in progress
+  let building = false;
+
+  // Queue a rebuild if one arrives while building
+  let pendingRebuild = false;
+
+  printBanner(config, { debounceMs: effectiveDebounce });
+
+  /**
+   * Execute the pipeline and refresh watchers afterwards
+   */
+  async function executePipeline() {
+    if (!watchState.active) return;
+
+    if (building) {
+      pendingRebuild = true;
+      return;
+    }
+
+    building = true;
+    pendingRebuild = false;
+
+    let result;
+    try {
+      result = await runPipeline(config, watchState);
+    } catch (err) {
+      watchState.errorCount = (watchState.errorCount || 0) + 1;
+      console.error(timestamp() + ' \u{1F525} Unhandled pipeline error: ' + (err && err.message));
+      if (typeof onError === 'function') {
+        try { onError(err); } catch (_) {}
+      }
+      result = { success: false, error: err };
+    }
+
+    // Refresh watchers to cover any new files/dirs discovered
+    if (result && result.filePaths && result.filePaths.length > 0) {
+      refreshWatchers(watchers, result.filePaths, rootDir, debouncedChange, config);
+    }
+
+    if (typeof onRebuild === 'function') {
+      try { onRebuild(result); } catch (_) {}
+    }
+
+    building = false;
+
+    // If a change arrived while we were building, run again
+    if (pendingRebuild && watchState.active) {
+      pendingRebuild = false;
+      setImmediate(executePipeline);
+    }
+  }
+
+  /**
+   * Handle a raw fs.watch event
+   * @param {string} eventType
+   * @param {string} changedPath
+   */
+  function handleChange(eventType, changedPath) {
+    if (!watchState.active) return;
+    if (!shouldRebuild(changedPath, config)) return;
+
+    if (config.verbose) {
+      console.log(timestamp() + ' \u{1F440} ' + eventType + ': ' + changedPath);
+    }
+
+    executePipeline();
+  }
+
+  const debouncedChange = debounce(handleChange, effectiveDebounce);
+
+  // Initial scan to discover files and set up watchers
+  let initialFilePaths = [];
+  try {
+    const initialScan = await scanProject(config);
+    if (initialScan && Array.isArray(initialScan.files)) {
+      initialFilePaths = initialScan.files.map(function (f) {
+        return f && (f.absolutePath || f.path);
+      }).filter(Boolean);
+    }
+  } catch (err) {
+    if (config.verbose) {
+      console.warn(timestamp() + ' \u26A0\uFE0F  Initial scan for watch targets failed: ' + (err && err.message));
+    }
+  }
+
+  const initialTargets = collectWatchTargets(initialFilePaths, rootDir);
+  watchers = attachWatchers(initialTargets, debouncedChange, config);
+
+  console.log(
+    timestamp() +
+    ' \u{1F440} Watching ' + watchers.size + ' path(s) for changes...'
+  );
+
+  // Run pipeline immediately on start
+  if (shouldRunOnStart) {
+    await executePipeline();
+  }
+
+  // Graceful shutdown on SIGINT / SIGTERM
+  function shutdown(signal) {
+    if (!watchState.active) return;
+    watchState.active = false;
+    console.log('\n' + timestamp() + ' \u{1F6D1} Received ' + signal + ', shutting down watch mode...');
+    closeWatchers(watchers);
+    printExitSummary(watchState);
+    process.exit(0);
+  }
+
+  process.once('SIGINT', function () { shutdown('SIGINT'); });
+  process.once('SIGTERM', function () { shutdown('SIGTERM'); });
+
+  /**
+   * Programmatic stop handle — allows callers to stop watch mode without
+   * killing the process (useful in tests or when embedded in a larger CLI).
+   */
+  function stop() {
+    if (!watchState.active) return;
+    watchState.active = false;
+    closeWatchers(watchers);
+    printExitSummary(watchState);
+  }
+
+  /**
+   * Return a snapshot of the current watch state
+   * @returns {object}
+   */
+  function getState() {
+    return Object.assign({}, watchState);
+  }
+
+  return { stop, getState };
+}
+
+module.exports = watchMode;