@opendatalabs/darshana 1.2.0 → 1.3.0

package/README.md

@@ -27,6 +27,11 @@ npm install -g @opendatalabs/darshana
 
 Chromium is installed automatically. Or skip the install entirely and use `npx @opendatalabs/darshana`.
 
+**Linux only:** if Chromium fails to launch, you may be missing system libraries. Fix with:
+```bash
+sudo npx playwright install chromium --with-deps
+```
+
 ## CLI reference
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendatalabs/darshana",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Crawl any web app and generate a labeled PDF, HTML viewer, or image set for design review.",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "path-to-regexp": "^8.0.0"
   },
   "scripts": {
-    "postinstall": "playwright install chromium --with-deps 2>/dev/null || playwright install chromium"
+    "postinstall": "playwright install chromium"
   },
   "devDependencies": {
     "semantic-release": "^25.0.0",

package/src/capture.mjs

@@ -7,6 +7,8 @@ export async function captureAll(browser, config, urls) {
   const results = [];
   const themes = config.capture.themes;
   const viewportNames = config.capture.viewports;
+  const total = urls.length * themes.length * viewportNames.length;
+  const counter = { n: 0 };
 
   for (const viewportName of viewportNames) {
     for (const theme of themes) {
@@ -20,7 +22,7 @@ export async function captureAll(browser, config, urls) {
         ...(storageStatePath ? { storageState: storageStatePath } : {}),
       };
 
-      console.log(`\n[capture] Segment: ${viewportName} / ${theme} (${urls.length} URLs)`);
+      console.log(`\n[capture] Starting segment ${viewportName}/${theme} (${urls.length} URLs)`);
       const context = await browser.newContext(contextOpts);
 
       for (const url of urls) {
@@ -31,20 +33,23 @@ export async function captureAll(browser, config, urls) {
 
         const effectiveThemes = override?.themes;
         if (effectiveThemes && !effectiveThemes.includes(theme)) {
-          console.log(`  [capture] skip ${pathname} [${theme}] (override)`);
+          counter.n++;
+          console.log(`  [capture] ${counter.n}/${total} skip ${pathname} [${theme}] (override)`);
           continue;
         }
         const effectiveViewports = override?.viewports;
         if (effectiveViewports && !effectiveViewports.includes(viewportName)) {
-          console.log(`  [capture] skip ${pathname} [${viewportName}] (override)`);
+          counter.n++;
+          console.log(`  [capture] ${counter.n}/${total} skip ${pathname} [${viewportName}] (override)`);
           continue;
         }
 
         const delay = override?.delay ?? config.capture.delay ?? 400;
         const waitFor = override?.waitFor ?? config.capture.waitFor ?? null;
         const label = makeLabel(pathname, viewportName, theme);
+        counter.n++;
 
-        console.log(`  [capture] ${label}`);
+        console.log(`  [capture] ${counter.n}/${total}  ${label}`);
         const page = await context.newPage();
 
         try {
@@ -96,14 +101,14 @@ export async function captureAll(browser, config, urls) {
 
           results.push({ url, pathname, theme, viewport: viewportName, imageBuffer, label });
         } catch (err) {
-          console.error(`  [capture] FAILED ${pathname}: ${err.message}`);
+          console.error(`  [capture] ${counter.n}/${total}  FAILED ${pathname}: ${err.message}`);
         } finally {
           await page.close();
         }
       }
 
       await context.close();
-      console.log(`[capture] Segment done: ${viewportName} / ${theme}`);
+      console.log(`[capture] Segment done: ${viewportName}/${theme}`);
     }
   }
 

package/src/config.mjs

@@ -6,6 +6,33 @@ export const VIEWPORT_PRESETS = {
   mobile:  { width: 390,  height: 844, deviceScaleFactor: 2 },
 };
 
+const KNOWN_TOP_LEVEL_KEYS = ['title', 'url', 'start', 'public', 'authStorage', 'authScript', 'crawl', 'capture', 'pdf', 'outputs', 'outputDir'];
+const KNOWN_CRAWL_KEYS = ['include', 'exclude', 'maxDepth', 'maxPages', 'extraRoutes', 'routes'];
+const KNOWN_CAPTURE_KEYS = ['themes', 'viewports', 'fullPage', 'delay', 'waitFor', 'contextOptions', 'launchOptions', 'playwrightOptions', 'routeOptions', 'overrides'];
+
+function levenshtein(a, b) {
+  const m = a.length, n = b.length;
+  const dp = Array.from({ length: m + 1 }, (_, i) => Array.from({ length: n + 1 }, (_, j) => i === 0 ? j : j === 0 ? i : 0));
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+
+function warnUnknownKeys(obj, knownKeys, section) {
+  if (!obj || typeof obj !== 'object') return;
+  for (const key of Object.keys(obj)) {
+    if (!knownKeys.includes(key)) {
+      const best = knownKeys.reduce((acc, k) => { const d = levenshtein(key, k); return d < acc.d ? { k, d } : acc; }, { k: null, d: Infinity });
+      const prefix = section ? `[darshana] Warning: unknown config field "${section}.${key}"` : `[darshana] Warning: unknown config field "${key}"`;
+      const suffix = best.d <= 3 ? ` — did you mean "${section ? section + '.' : ''}${best.k}"?` : '';
+      console.warn(prefix + suffix);
+    }
+  }
+}
+
 export function loadConfig(configPath) {
   const absConfigPath = path.resolve(configPath);
   const configDir = path.dirname(absConfigPath);
@@ -25,6 +52,10 @@ export function loadConfig(configPath) {
 // Build a config object from a plain object (used by both loadConfig and CLI --url mode).
 // configDir is used to resolve relative paths; defaults to cwd when not loading from a file.
 export function buildConfig(raw, configDir = process.cwd()) {
+  // Validate unknown keys and emit typo hints
+  warnUnknownKeys(raw, KNOWN_TOP_LEVEL_KEYS, null);
+  warnUnknownKeys(raw.crawl, KNOWN_CRAWL_KEYS, 'crawl');
+  warnUnknownKeys(raw.capture, KNOWN_CAPTURE_KEYS, 'capture');
   const config = {
     title: raw.title ?? 'Design Review',
     url: raw.url.replace(/\/$/, ''),

package/src/index.mjs

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
 import path from 'node:path';
+import readline from 'node:readline';
+import { createRequire } from 'node:module';
 import { chromium } from 'playwright';
 import { loadConfig, buildConfig } from './config.mjs';
 import { ensureAuth } from './auth.mjs';
@@ -9,6 +11,9 @@ import { captureAll } from './capture.mjs';
 import { assemblePdf } from './pdf.mjs';
 import { assembleHtml } from './html.mjs';
 
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
 const USAGE = `
 Usage:
   darshana --url <url> [options]          # zero-config mode
@@ -36,6 +41,155 @@ Options:
   --auth-only              Save auth session and exit
 `.trim();
 
+// ── Config summary box ────────────────────────────────────────────────────────
+
+function printConfigSummary(config) {
+  const INNER = 48;
+  const authLabel = config.public
+    ? 'public'
+    : config.authScript
+      ? `script: ${path.basename(config.authScript)}`
+      : 'session file';
+
+  const rows = [
+    ['url',       config.url],
+    ['start',     config.start],
+    ['auth',      authLabel],
+    ['themes',    (config.capture.themes ?? ['system']).join(', ')],
+    ['viewports', (config.capture.viewports ?? ['desktop']).join(', ')],
+    ['maxPages',  `${config.crawl.maxPages}  maxDepth  ${config.crawl.maxDepth}`],
+    ['outputs',   (config.outputs ?? ['pdf', 'html']).join(', ')],
+    ['outputDir', config.outputDir ?? './darshana-output'],
+  ];
+
+  // Compute column widths
+  const keyWidth = Math.max(...rows.map(([k]) => k.length));
+  const valWidth = INNER - keyWidth - 2; // 2 = space + space
+
+  function trunc(s, max) {
+    const str = String(s);
+    return str.length > max ? str.slice(0, max - 1) + '…' : str;
+  }
+
+  function pad(s, len) { return s + ' '.repeat(Math.max(0, len - s.length)); }
+
+  const topLabel = ' darshana ';
+  const topLineLen = INNER + 2; // borders
+  const dashLen = topLineLen - topLabel.length - 2; // -2 for corner chars
+  const dashLeft = Math.floor(dashLen / 2);
+  const dashRight = dashLen - dashLeft;
+
+  console.log(`┌${'─'.repeat(dashLeft)}${topLabel}${'─'.repeat(dashRight)}┐`);
+  for (const [k, v] of rows) {
+    const paddedKey = pad(k, keyWidth);
+    const truncVal = trunc(v, valWidth);
+    const paddedVal = pad(truncVal, valWidth);
+    console.log(`│ ${paddedKey} ${paddedVal} │`);
+  }
+  console.log(`└${'─'.repeat(INNER)}┘`);
+}
+
+// ── init subcommand ───────────────────────────────────────────────────────────
+
+async function runInit() {
+  const configPath = path.join(process.cwd(), 'review.config.json');
+
+  // Build an `ask` function that works for both TTY and piped stdin.
+  // For piped input: readline fires 'close' as soon as the pipe ends, breaking
+  // sequential question() calls. We buffer all lines upfront and serve them.
+  // For interactive TTY: use readline.question() normally.
+  const ask = await makeAsker();
+
+  if (fs.existsSync(configPath)) {
+    const overwrite = await ask('review.config.json already exists. Overwrite? (y/N): ');
+    if (overwrite.trim().toLowerCase() !== 'y') {
+      console.log('Aborted.');
+      process.exit(0);
+    }
+  }
+
+  // 1. URL
+  let url;
+  while (true) {
+    const raw = await ask('App URL (e.g. https://myapp.example.com): ');
+    try { url = new URL(raw.trim()).href.replace(/\/$/, ''); break; }
+    catch { console.log('  Invalid URL. Please include the scheme (https://).'); }
+  }
+  const hostname = new URL(url).hostname;
+
+  // 2. Title
+  const titleRaw = await ask(`Title (default: ${hostname}): `);
+  const title = titleRaw.trim() || hostname;
+
+  // 3. Auth
+  const authRaw = await ask('Is the app public? (y/N): ');
+  const isPublic = authRaw.trim().toLowerCase() === 'y';
+
+  // 4. Start path
+  const startRaw = await ask('Start path (default: /): ');
+  const start = startRaw.trim() || '/';
+
+  // 5. Viewports
+  const vpRaw = await ask('Viewports — desktop, mobile, or both? (default: desktop): ');
+  const vpInput = vpRaw.trim().toLowerCase() || 'desktop';
+  let viewports;
+  if (vpInput === 'both') viewports = ['desktop', 'mobile'];
+  else if (vpInput === 'mobile') viewports = ['mobile'];
+  else viewports = ['desktop'];
+
+  // 6. Themes
+  const themeRaw = await ask('Themes — system, dark, light, or multiple? (default: system): ');
+  const themeInput = themeRaw.trim() || 'system';
+  let themes;
+  if (themeInput === 'multiple' || themeInput.includes(',')) {
+    themes = themeInput === 'multiple'
+      ? ['dark', 'light']
+      : themeInput.split(',').map(s => s.trim()).filter(Boolean);
+  } else {
+    themes = [themeInput];
+  }
+
+  // 7. Output dir
+  const outRaw = await ask('Output directory (default: ./darshana-output): ');
+  const outputDir = outRaw.trim() || './darshana-output';
+
+  const config = {
+    title,
+    url,
+    start,
+    public: isPublic,
+    capture: { viewports, themes },
+    outputDir,
+  };
+
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  console.log('✓ review.config.json created. Run: darshana --config review.config.json');
+  process.exit(0);
+}
+
+// Returns an `ask(question)` function.
+// TTY mode: wraps readline.question for interactive line editing.
+// Piped mode: buffers all stdin lines first, then serves them sequentially.
+async function makeAsker() {
+  if (process.stdin.isTTY) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return (q) => new Promise(resolve => rl.question(q, answer => { resolve(answer); }));
+  }
+  // Non-TTY: read all lines from stdin before asking anything
+  const lines = await new Promise(resolve => {
+    const buf = [];
+    const rl = readline.createInterface({ input: process.stdin });
+    rl.on('line', l => buf.push(l));
+    rl.on('close', () => resolve(buf));
+  });
+  let idx = 0;
+  return (q) => {
+    const answer = lines[idx++] ?? '';
+    console.log(`${q}${answer}`);
+    return Promise.resolve(answer);
+  };
+}
+
 function parseArgs(argv) {
   const args = {
     config: null,
@@ -82,6 +236,7 @@ function parseArgs(argv) {
     if (a === '--route')        { args.route = next(); continue; }
     if (a === '--auth-only')    { args.authOnly = true; continue; }
     if (a === '--help' || a === '-h') { console.log(USAGE); process.exit(0); }
+    if (a === '--version' || a === '-v') { console.log(`darshana ${pkg.version}`); process.exit(0); }
     console.error(`Unknown argument: ${a}\n\n${USAGE}`);
     process.exit(1);
   }
@@ -136,95 +291,109 @@ function applyCliOverrides(config, args) {
   return config;
 }
 
-const args = parseArgs(process.argv.slice(2));
-
-if (!args.config && !args.url) {
-  console.error('Error: --url or --config is required\n\n' + USAGE);
-  process.exit(1);
+// Dispatch init before parseArgs so we don't need --url
+if (process.argv[2] === 'init') {
+  runInit();
+} else {
+  runMain();
 }
 
-async function main() {
-  let config;
-  if (args.config) {
-    config = loadConfig(args.config);
-    config = applyCliOverrides(config, args);
-  } else {
-    config = configFromArgs(args);
+function runMain() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.config && !args.url) {
+    console.error('Error: --url or --config is required\n\n' + USAGE);
+    process.exit(1);
   }
 
-  console.log(`[darshana] ${config.title} — ${config.url}`);
+  async function main() {
+    let config;
+    if (args.config) {
+      config = loadConfig(args.config);
+      config = applyCliOverrides(config, args);
+    } else {
+      config = configFromArgs(args);
+    }
 
-  const storageStatePath = await ensureAuth(config);
-  config._storageStatePath = storageStatePath;
+    const storageStatePath = await ensureAuth(config);
+    config._storageStatePath = storageStatePath;
 
-  if (args.authOnly) {
-    console.log('[darshana] --auth-only done.');
-    process.exit(0);
-  }
+    printConfigSummary(config);
 
-  let urls;
-  if (args.route) {
-    const fullUrl = args.route.startsWith('http') ? args.route : config.url + args.route;
-    urls = [fullUrl];
-    console.log(`[darshana] --route mode: ${fullUrl}`);
-  } else {
-    const crawlBrowser = await chromium.launch({ headless: true });
-    const crawlContextOpts = storageStatePath ? { storageState: storageStatePath } : {};
-    const crawlContext = await crawlBrowser.newContext(crawlContextOpts);
-    try {
-      console.log(`[darshana] Crawling from ${config.url}${config.start} ...`);
-      urls = await crawl(crawlContext, config);
-    } finally {
-      await crawlContext.close();
-      await crawlBrowser.close();
+    if (args.authOnly) {
+      console.log('[darshana] --auth-only done.');
+      process.exit(0);
     }
-    console.log(`[darshana] Crawl complete: ${urls.length} URLs found.`);
-  }
 
-  if (args.dryRun) {
-    console.log('\n[darshana] --dry-run: discovered URLs:');
-    for (const u of urls) console.log(`  ${u}`);
-    process.exit(0);
-  }
+    let urls;
+    if (args.route) {
+      const fullUrl = args.route.startsWith('http') ? args.route : config.url + args.route;
+      urls = [fullUrl];
+      console.log(`[darshana] --route mode: ${fullUrl}`);
+    } else {
+      const crawlBrowser = await chromium.launch({ headless: true });
+      const crawlContextOpts = storageStatePath ? { storageState: storageStatePath } : {};
+      const crawlContext = await crawlBrowser.newContext(crawlContextOpts);
+      try {
+        console.log(`[darshana] Crawling from ${config.url}${config.start} ...`);
+        urls = await crawl(crawlContext, config);
+      } finally {
+        await crawlContext.close();
+        await crawlBrowser.close();
+      }
+      console.log(`[darshana] Crawl complete: ${urls.length} URLs found.`);
+    }
 
-  const browser = await chromium.launch({
-    headless: true,
-    args: ['--no-sandbox', '--disable-setuid-sandbox'],
-    ...(config.capture.launchOptions ?? {}),
-  });
+    if (args.dryRun) {
+      console.log('\n[darshana] --dry-run: discovered URLs:');
+      for (const u of urls) console.log(`  ${u}`);
+      process.exit(0);
+    }
 
-  let captures;
-  try {
-    captures = await captureAll(browser, config, urls);
-  } finally {
-    await browser.close();
-  }
+    const browser = await chromium.launch({
+      headless: true,
+      args: ['--no-sandbox', '--disable-setuid-sandbox'],
+      ...(config.capture.launchOptions ?? {}),
+    });
 
-  console.log(`\n[darshana] Captured ${captures.length} page(s).`);
+    let captures;
+    try {
+      captures = await captureAll(browser, config, urls);
+    } finally {
+      await browser.close();
+    }
 
-  if (captures.length === 0) {
-    console.error('[darshana] No pages captured. Exiting.');
-    process.exit(1);
-  }
+    console.log(`\n[darshana] Captured ${captures.length} page(s).`);
 
-  const outputDir = config.outputDir;
-  fs.mkdirSync(outputDir, { recursive: true });
+    if (captures.length === 0) {
+      console.error('[darshana] No pages captured. Exiting.');
+      process.exit(1);
+    }
 
-  const outputs = config.outputs ?? ['pdf', 'html'];
+    const outputDir = config.outputDir;
+    fs.mkdirSync(outputDir, { recursive: true });
 
-  if (outputs.includes('pdf')) {
-    await assemblePdf(captures, config, outputDir);
-  }
+    const outputs = config.outputs ?? ['pdf', 'html'];
 
-  if (outputs.includes('html')) {
-    await assembleHtml(captures, config, outputDir);
-  }
+    if (outputs.includes('pdf')) {
+      await assemblePdf(captures, config, outputDir);
+    }
 
-  if (outputs.includes('images')) {
-    await writeImages(captures, outputDir);
+    if (outputs.includes('html')) {
+      await assembleHtml(captures, config, outputDir);
+    }
+
+    if (outputs.includes('images')) {
+      await writeImages(captures, outputDir);
+    }
+
+    console.log('\n[darshana] Done.');
   }
 
-  console.log('\n[darshana] Done.');
+  main().catch(err => {
+    console.error('[darshana] Fatal:', err);
+    process.exit(1);
+  });
 }
 
 async function writeImages(captures, outputDir) {
@@ -257,8 +426,3 @@ function slugifyPathname(pathname) {
     .replace(/^-|-$/g, '')
     || 'root';
 }
-
-main().catch(err => {
-  console.error('[darshana] Fatal:', err);
-  process.exit(1);
-});