@kaze-no-ryuu/argus 0.3.0 → 0.4.0

package/README.md

@@ -3,11 +3,10 @@
 **Does what you built match the real thing?** Argus compares your local site, page by page and at desktop, tablet and mobile sizes, against a **live reference site** and/or **design images**. It tells you how much changed and *which element* changed.
 
 ```bash
-npm i -D @kaze-no-ryuu/argus && npx playwright install chromium
-npx argus
+npx @kaze-no-ryuu/argus
 ```
 
-The first run detects your framework, writes a config and adds an `argus` npm script. Every run after that starts your dev server, screenshots everything, diffs it and writes one HTML report.
+That's the whole setup. The first run downloads Chromium if it isn't installed yet, detects your framework, writes a config and adds an `argus` npm script. Every run after that starts your dev server, screenshots everything, diffs it and writes one HTML report.
 
 ## Why Argus
 
@@ -37,12 +36,13 @@ Use the hosted services when you need a team review flow for screenshots that ch
 ## Quick start
 
 ```bash
-npm i -D @kaze-no-ryuu/argus
-npx playwright install chromium   # once, downloads the browser
+npm i -D @kaze-no-ryuu/argus      # pin the version in your project (optional, recommended for CI)
 npx argus init                    # detects your framework, writes argus.config.json, adds an npm script
-npm run argus
+npm run argus                     # first run downloads Chromium (~100 MB, once)
 ```
 
+On a fresh Linux machine or CI image, Chromium also needs system libraries. Install them once with `npx playwright install-deps chromium` (needs root).
+
 Running `npx argus` without a config does the `init` step for you.
 
 > The npm package is `@kaze-no-ryuu/argus` and the command is `argus`. Without a local install, run `npx @kaze-no-ryuu/argus` instead. `npx argus` would fetch an unrelated package.

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { type Browser } from 'playwright';
 import type { Band, Box, Config, Log, Page, RawConfig, Result, RunOptions, Summary, Viewport } from './types.ts';
 export type * from './types.ts';
 export declare const CONFIG_FILE = "argus.config.json";
@@ -9,6 +10,8 @@ export declare const DEFAULTS: {
     settle: number;
     serverTimeout: number;
 };
+export declare const isMissingBrowser: (e: unknown) => boolean;
+export declare function launchBrowser(log: Log): Promise<Browser>;
 export declare function loadConfig(file?: string): Config;
 export declare function normalizeConfig(raw: RawConfig, root?: string): Config;
 export declare function pageName(p: string): string;

package/dist/index.js

@@ -1,6 +1,7 @@
 import { chromium } from 'playwright';
 import { compare } from 'odiff-bin';
-import { spawn, execSync } from 'node:child_process';
+import { spawn, execSync, execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
 import fs from 'node:fs';
 import { setTimeout as sleep } from 'node:timers/promises';
 import os from 'node:os';
@@ -20,6 +21,23 @@ export const DEFAULTS = {
     serverTimeout: 120000,
 };
 const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+export const isMissingBrowser = (e) => /Executable doesn't exist/.test(errMsg(e));
+// Launches Chromium, downloading it first if it isn't installed yet, so
+// `npx argus` works without a separate `playwright install` step.
+export async function launchBrowser(log) {
+    try {
+        return await chromium.launch();
+    }
+    catch (e) {
+        if (!isMissingBrowser(e))
+            throw e;
+        log('Chromium is not installed yet, downloading it (one time, ~100 MB)...');
+        const cli = path.join(path.dirname(createRequire(import.meta.url).resolve('playwright')), 'cli.js');
+        // Output goes to stderr so --json stdout stays clean.
+        execFileSync(process.execPath, [cli, 'install', 'chromium'], { stdio: ['ignore', 2, 2] });
+        return chromium.launch();
+    }
+}
 // Fills defaults and resolves file paths relative to the config file.
 export function loadConfig(file = CONFIG_FILE) {
     const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -391,7 +409,7 @@ export async function run(cfg, opts = {}) {
         }
         let browser;
         if (doShoot)
-            browser = browserWs ? await chromium.connect(browserWs) : await chromium.launch();
+            browser = browserWs ? await chromium.connect(browserWs) : await launchBrowser(log);
         try {
             const ctxs = new Map();
             if (browser) {

package/dist/init.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import readline from 'node:readline/promises';
 import { CONFIG_FILE, DEFAULTS } from './index.js';
 const PLACEHOLDER = 'https://example.com';
+const SELF = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).name;
 const SKIP_DIRS = /(^|\/)(node_modules|dist|build|out|\.git|\.next|\.astro|\.svelte-kit|\.nuxt|coverage|argus)(\/|$)/;
 function list(cwd, dir) {
     try {
@@ -138,10 +139,12 @@ export async function init({ cwd = process.cwd(), remote, force = false, yes = f
         const text = fs.readFileSync(pkgPath, 'utf8');
         const pkg = JSON.parse(text);
         if (!pkg.scripts?.['argus']) {
-            pkg.scripts = { ...pkg.scripts, 'argus': 'argus' };
+            // The `argus` bin only exists when the package is installed in the project.
+            const installed = SELF in { ...pkg.dependencies, ...pkg.devDependencies };
+            pkg.scripts = { ...pkg.scripts, argus: installed ? 'argus' : `npx ${SELF}` };
             const indent = text.match(/^[ \t]+(?=")/m)?.[0] ?? '  ';
             fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`);
-            log('added "argus" script to package.json');
+            log(`added "argus" script to package.json: ${pkg.scripts.argus}`);
         }
     }
     const gi = path.join(cwd, '.gitignore');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaze-no-ryuu/argus",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Argus: visual diff of your local site against a live site or design images. Auto-detects framework and dev server, desktop/tablet/mobile, pinpoints changed elements, HTML report + JSON for CI and AI agents.",
   "type": "module",
   "bin": {