@opendatalabs/darshana 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendatalabs/darshana",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Crawl any web app and generate a labeled PDF, HTML viewer, or image set for design review.",
   "type": "module",
   "bin": {

package/src/capture.mjs

@@ -63,17 +63,20 @@ export async function captureAll(browser, config, urls) {
           await page.goto(url, { waitUntil: 'networkidle', timeout: 60000 });
           await page.addStyleTag({ content: NEXTJS_HIDE_STYLE }).catch(() => {});
 
-          await page.evaluate((t) => {
-            const html = document.documentElement;
-            html.setAttribute('data-theme', t);
-            if (t === 'dark') {
-              html.classList.add('dark');
-              html.classList.remove('light');
-            } else {
-              html.classList.add('light');
-              html.classList.remove('dark');
-            }
-          }, theme);
+          // 'system' = no injection; let the page's own prefers-color-scheme take effect
+          if (theme !== 'system') {
+            await page.evaluate((t) => {
+              const html = document.documentElement;
+              html.setAttribute('data-theme', t);
+              if (t === 'dark') {
+                html.classList.add('dark');
+                html.classList.remove('light');
+              } else {
+                html.classList.add('light');
+                html.classList.remove('dark');
+              }
+            }, theme);
+          }
 
           if (waitFor) {
             if (waitFor.startsWith('$')) {

package/src/config.mjs

@@ -19,10 +19,16 @@ export function loadConfig(configPath) {
   if (!raw.url) throw new Error('Config missing required field: url');
   if (!raw.start) throw new Error('Config missing required field: start');
 
+  return buildConfig(raw, configDir);
+}
+
+// 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()) {
   const config = {
     title: raw.title ?? 'Design Review',
     url: raw.url.replace(/\/$/, ''),
-    start: raw.start,
+    start: raw.start ?? '/',
     public: raw.public ?? false,
     authStorage: raw.authStorage ?? './auth.json',
     authScript: raw.authScript ?? null,
@@ -37,7 +43,7 @@ export function loadConfig(configPath) {
     },
 
     capture: {
-      themes: raw.capture?.themes ?? ['dark'],
+      themes: raw.capture?.themes ?? ['system'],
       viewports: raw.capture?.viewports ?? ['desktop'],
       fullPage: raw.capture?.fullPage ?? true,
       delay: raw.capture?.delay ?? 400,
@@ -50,11 +56,11 @@ export function loadConfig(configPath) {
     },
 
     pdf: {
-      output: raw.pdf?.output ?? './console-review.pdf',
+      output: raw.pdf?.output ?? './darshana-output/review.pdf',
       pageSize: raw.pdf?.pageSize ?? 'A4',
     },
 
-    outputs: raw.outputs ?? ['pdf'],
+    outputs: raw.outputs ?? ['pdf', 'html'],
     outputDir: raw.outputDir ? path.resolve(configDir, raw.outputDir) : null,
   };
 

package/src/index.mjs

@@ -2,33 +2,156 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { chromium } from 'playwright';
-import { loadConfig } from './config.mjs';
+import { loadConfig, buildConfig } from './config.mjs';
 import { ensureAuth } from './auth.mjs';
 import { crawl } from './crawl.mjs';
 import { captureAll } from './capture.mjs';
 import { assemblePdf } from './pdf.mjs';
 import { assembleHtml } from './html.mjs';
 
+const USAGE = `
+Usage:
+  darshana --url <url> [options]          # zero-config mode
+  darshana --config <path> [options]      # file-based config
+
+Options:
+  --url <url>              Base URL to crawl (required if no --config)
+  --config <path>          Path to a JSON config file
+  --title <string>         Review title (default: hostname)
+  --start <path>           Starting path (default: /)
+  --public                 Skip auth entirely
+  --auth-storage <path>    Path to saved Playwright storageState (default: ./auth.json)
+  --auth-script <path>     Path to a headless auth script
+  --themes <list>          Comma-separated: dark,light,system (default: system)
+  --viewports <list>       Comma-separated: desktop,mobile (default: desktop)
+  --max-depth <n>          BFS depth limit (default: 5)
+  --max-pages <n>          Page cap (default: 100)
+  --delay <ms>             Wait after page load before capture (default: 400)
+  --outputs <list>         Comma-separated: pdf,html,images (default: pdf,html)
+  --output-dir <path>      Directory for output files (default: ./darshana-output)
+  --include <regex>        Crawl only paths matching this pattern (repeatable)
+  --exclude <regex>        Skip paths matching this pattern (repeatable)
+  --dry-run                Discover URLs without capturing
+  --route <path>           Capture a single route only
+  --auth-only              Save auth session and exit
+`.trim();
+
 function parseArgs(argv) {
-  const args = { config: null, dryRun: false, route: null, authOnly: false };
+  const args = {
+    config: null,
+    url: null,
+    title: null,
+    start: null,
+    public: false,
+    authStorage: null,
+    authScript: null,
+    themes: null,
+    viewports: null,
+    maxDepth: null,
+    maxPages: null,
+    delay: null,
+    outputs: null,
+    outputDir: null,
+    include: [],
+    exclude: [],
+    dryRun: false,
+    route: null,
+    authOnly: false,
+  };
+
   for (let i = 0; i < argv.length; i++) {
-    if (argv[i] === '--config' && argv[i + 1]) { args.config = argv[++i]; continue; }
-    if (argv[i] === '--dry-run') { args.dryRun = true; continue; }
-    if (argv[i] === '--route' && argv[i + 1]) { args.route = argv[++i]; continue; }
-    if (argv[i] === '--auth-only') { args.authOnly = true; continue; }
+    const a = argv[i];
+    const next = () => { if (!argv[i + 1]) { console.error(`Missing value for ${a}`); process.exit(1); } return argv[++i]; };
+    if (a === '--config')       { args.config = next(); continue; }
+    if (a === '--url')          { args.url = next(); continue; }
+    if (a === '--title')        { args.title = next(); continue; }
+    if (a === '--start')        { args.start = next(); continue; }
+    if (a === '--public')       { args.public = true; continue; }
+    if (a === '--auth-storage') { args.authStorage = next(); continue; }
+    if (a === '--auth-script')  { args.authScript = next(); continue; }
+    if (a === '--themes')       { args.themes = next().split(',').map(s => s.trim()); continue; }
+    if (a === '--viewports')    { args.viewports = next().split(',').map(s => s.trim()); continue; }
+    if (a === '--max-depth')    { args.maxDepth = parseInt(next(), 10); continue; }
+    if (a === '--max-pages')    { args.maxPages = parseInt(next(), 10); continue; }
+    if (a === '--delay')        { args.delay = parseInt(next(), 10); continue; }
+    if (a === '--outputs')      { args.outputs = next().split(',').map(s => s.trim()); continue; }
+    if (a === '--output-dir')   { args.outputDir = next(); continue; }
+    if (a === '--include')      { args.include.push(next()); continue; }
+    if (a === '--exclude')      { args.exclude.push(next()); continue; }
+    if (a === '--dry-run')      { args.dryRun = true; continue; }
+    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); }
+    console.error(`Unknown argument: ${a}\n\n${USAGE}`);
+    process.exit(1);
   }
   return args;
 }
 
+function configFromArgs(args) {
+  const url = args.url.replace(/\/$/, '');
+  const hostname = new URL(url).hostname;
+  const outputDir = args.outputDir ?? './darshana-output';
+
+  const raw = {
+    title: args.title ?? hostname,
+    url,
+    start: args.start ?? '/',
+    public: args.public,
+    authStorage: args.authStorage ?? path.join(outputDir, 'auth.json'),
+    authScript: args.authScript ?? null,
+    crawl: {
+      include: args.include,
+      exclude: args.exclude,
+      maxDepth: args.maxDepth ?? 5,
+      maxPages: args.maxPages ?? 100,
+    },
+    capture: {
+      themes: args.themes ?? ['system'],
+      viewports: args.viewports ?? ['desktop'],
+      delay: args.delay ?? 400,
+    },
+    outputs: args.outputs ?? ['pdf', 'html'],
+    outputDir,
+  };
+
+  return buildConfig(raw, process.cwd());
+}
+
+function applyCliOverrides(config, args) {
+  if (args.title)     config.title = args.title;
+  if (args.start)     config.start = args.start;
+  if (args.public)    config.public = true;
+  if (args.authStorage) config.authStorage = path.resolve(args.authStorage);
+  if (args.authScript)  config.authScript = path.resolve(args.authScript);
+  if (args.themes)    config.capture.themes = args.themes;
+  if (args.viewports) config.capture.viewports = args.viewports;
+  if (args.maxDepth)  config.crawl.maxDepth = args.maxDepth;
+  if (args.maxPages)  config.crawl.maxPages = args.maxPages;
+  if (args.delay)     config.capture.delay = args.delay;
+  if (args.outputs)   config.outputs = args.outputs;
+  if (args.outputDir) config.outputDir = path.resolve(args.outputDir);
+  if (args.include.length) config.crawl.include = [...config.crawl.include, ...args.include];
+  if (args.exclude.length) config.crawl.exclude = [...config.crawl.exclude, ...args.exclude];
+  return config;
+}
+
 const args = parseArgs(process.argv.slice(2));
 
-if (!args.config) {
-  console.error('Usage: darshana --config <path> [--dry-run] [--route <path>] [--auth-only]');
+if (!args.config && !args.url) {
+  console.error('Error: --url or --config is required\n\n' + USAGE);
   process.exit(1);
 }
 
 async function main() {
-  const config = loadConfig(args.config);
+  let config;
+  if (args.config) {
+    config = loadConfig(args.config);
+    config = applyCliOverrides(config, args);
+  } else {
+    config = configFromArgs(args);
+  }
+
   console.log(`[darshana] ${config.title} — ${config.url}`);
 
   const storageStatePath = await ensureAuth(config);
@@ -87,7 +210,7 @@ async function main() {
   const outputDir = config.outputDir;
   fs.mkdirSync(outputDir, { recursive: true });
 
-  const outputs = config.outputs ?? ['pdf'];
+  const outputs = config.outputs ?? ['pdf', 'html'];
 
   if (outputs.includes('pdf')) {
     await assemblePdf(captures, config, outputDir);