samey-cli 0.0.0-stage → 0.1.0

package/dist/audit.js

@@ -0,0 +1,250 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { checkModel, critiqueScreens } from './ai/local-model.js';
+import { BrowserMissingError, crawl, launchBrowser, VIEWPORTS } from './render/crawl.js';
+import { serveStatic, startDevServer } from './render/server.js';
+import { renderHtml } from './report/html.js';
+import { fullPrompt } from './report/prompt.js';
+import { rulePenalties, ruleVersions, runRules } from './rules/index.js';
+import { normalizeFindings } from './rules/normalize.js';
+import { CATEGORY_LABELS, prioritize, SCORING, scoreFindings } from './score.js';
+import { BlockedError, displayUrl, DEV_POLICY, REMOTE_POLICY, resolveTarget } from './security/net-policy.js';
+import { scanRepo } from './static/scan.js';
+export function toolVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        return JSON.parse(readFileSync(path.join(here, '..', 'package.json'), 'utf8')).version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export class AuditError extends Error {
+}
+export async function runAudit(opts) {
+    const began = Date.now();
+    const log = opts.onProgress ?? (() => undefined);
+    if (!opts.path && !opts.url)
+        throw new AuditError('Nothing to audit: pass a project path, --url, or both.');
+    // Validate the URL before doing any other work. Non-public addresses need explicit --dev.
+    const urlPolicy = opts.policyOverride ?? (opts.dev ? DEV_POLICY : REMOTE_POLICY);
+    if (opts.url) {
+        try {
+            await resolveTarget(opts.url, urlPolicy);
+        }
+        catch (err) {
+            if (!(err instanceof BlockedError))
+                throw err;
+            const local = /loopback|private/.test(err.message);
+            throw new AuditError(local && !opts.dev
+                ? `${err.message}. To audit a local or private development server, pass --dev.`
+                : `Refusing to audit ${opts.url}: ${err.message}.`);
+        }
+    }
+    const outDir = path.resolve(opts.outDir);
+    const shotsDir = path.join(outDir, 'shots');
+    mkdirSync(outDir, { recursive: true });
+    // Clear screenshots from a previous run so the report never shows stale images.
+    try {
+        for (const f of readdirSync(shotsDir))
+            if (f.endsWith('.jpg'))
+                rmSync(path.join(shotsDir, f));
+    }
+    catch {
+        /* no previous shots */
+    }
+    const coverage = {
+        staticAnalysis: false,
+        rendered: false,
+        renderAttempted: false,
+        pagesAudited: 0,
+        pagesFailed: 0,
+        routeLimitHit: false,
+        skipped: [],
+        interactions: false,
+        blockedRequests: [],
+        networkBudgetExceeded: false,
+        model: { enabled: false },
+        limitations: [],
+    };
+    let repo;
+    if (opts.path) {
+        log(`Scanning ${path.relative(process.cwd(), opts.path) || '.'}`);
+        repo = scanRepo(opts.path);
+        coverage.staticAnalysis = true;
+        log(`Found ${repo.fileCount} source files${repo.frameworks.length ? ` (${repo.frameworks.join(', ')})` : ''}${repo.truncated ? ', file limit reached' : ''}`);
+    }
+    let crawlResult;
+    let server;
+    try {
+        let target = opts.url;
+        if (!target && !opts.staticOnly && repo) {
+            if (opts.serve) {
+                log(`Starting dev server: ${opts.serve}`);
+                server = await startDevServer(opts.serve, repo.root, opts.port, opts.serverTimeoutMs);
+                target = server.url;
+            }
+            else if (repo.staticRoot) {
+                server = await serveStatic(repo.staticRoot);
+                target = server.url;
+                log(`Serving ${path.relative(process.cwd(), repo.staticRoot) || '.'} at ${target}`);
+            }
+            else {
+                coverage.renderedNote =
+                    'No URL was given, the project has no static build to serve, and --serve was not passed, so rendered checks did not run. ' +
+                        "Pass --url http://localhost:3000 for a running server, or --serve 'npm run dev' to let samey start it.";
+            }
+        }
+        if (opts.staticOnly)
+            coverage.renderedNote = 'Rendered checks were disabled with --static-only.';
+        if (target) {
+            // A server samey started is on loopback; it does not need access to the rest of the private network.
+            const policy = opts.policyOverride ?? (server ? { allowLoopback: true, allowPrivate: false } : urlPolicy);
+            const browser = await launchBrowser(policy).catch((err) => {
+                if (err instanceof BrowserMissingError) {
+                    coverage.renderedNote = err.message;
+                    log(err.message);
+                    return undefined;
+                }
+                throw err;
+            });
+            if (browser) {
+                try {
+                    const isLocalProject = !!server || !!(repo && opts.url && opts.dev);
+                    crawlResult = await crawl(browser, {
+                        startUrl: target,
+                        maxRoutes: opts.maxRoutes,
+                        navTimeoutMs: opts.navTimeoutMs,
+                        pageTimeoutMs: opts.pageTimeoutMs,
+                        seeds: [...opts.routes, ...(isLocalProject && repo ? repo.routeHints : [])],
+                        shotsDir: opts.screenshots ? shotsDir : undefined,
+                        interact: opts.interact,
+                        respectRobots: opts.respectRobots && !isLocalProject,
+                        policy,
+                        onProgress: log,
+                    });
+                }
+                finally {
+                    await browser.close();
+                }
+                coverage.renderAttempted = true;
+                coverage.rendered = crawlResult.pages.some((p) => p.desktop);
+                coverage.pagesAudited = crawlResult.pages.length;
+                coverage.pagesFailed = crawlResult.pages.filter((p) => !p.desktop).length;
+                coverage.routeLimitHit = crawlResult.limitHit;
+                coverage.skipped = crawlResult.skipped;
+                coverage.interactions = opts.interact;
+                coverage.blockedRequests = crawlResult.network.blocked.slice(0, 20);
+                coverage.networkBudgetExceeded = crawlResult.network.budgetExceeded;
+                if (!coverage.rendered) {
+                    const why = crawlResult.pages.find((p) => p.error)?.error ?? (crawlResult.pages[0]?.status ? `HTTP ${crawlResult.pages[0].status}` : 'unknown error');
+                    coverage.renderedNote = `No page under ${server ? 'the local server' : target} could be rendered (${why}).`;
+                }
+            }
+        }
+    }
+    finally {
+        await server?.close();
+    }
+    log('Running rules');
+    const { findings, errors } = runRules({ crawl: crawlResult, repo }, opts.ignoreRules);
+    let modelFindings = [];
+    if (opts.ai && opts.model && crawlResult && opts.screenshots) {
+        const mopts = { model: opts.model, endpoint: opts.modelEndpoint, timeoutMs: opts.modelTimeoutMs, maxPages: 3 };
+        const check = await checkModel(mopts).catch((e) => ({ ok: false, note: e.message }));
+        coverage.model = { enabled: check.ok, name: opts.model, note: check.note };
+        if (check.ok) {
+            log(`Asking local model ${opts.model} for a visual critique`);
+            const drafts = await critiqueScreens(crawlResult, shotsDir, mopts).catch((e) => {
+                coverage.model.note = `model run failed: ${e.message}`;
+                return [];
+            });
+            modelFindings = normalizeFindings(drafts);
+        }
+    }
+    else {
+        coverage.model = {
+            enabled: false,
+            note: !opts.ai ? 'disabled with --no-ai' : !opts.model ? 'no local model configured (optional; see --model)' : 'needs rendered screenshots',
+        };
+    }
+    const all = [...findings, ...modelFindings];
+    const { score, categories } = scoreFindings(all, coverage, rulePenalties());
+    coverage.limitations = limitations(coverage, categories.filter((c) => c.score === null).map((c) => CATEGORY_LABELS[c.category]));
+    const pages = crawlResult?.pages ?? [];
+    const projectKey = repo?.root ?? (opts.url ? new URL(opts.url).origin : 'unknown');
+    const report = {
+        schemaVersion: 1,
+        scanId: randomUUID(),
+        tool: { name: 'samey', version: toolVersion() },
+        generatedAt: new Date().toISOString(),
+        durationMs: Date.now() - began,
+        project: { id: createHash('sha256').update(projectKey).digest('hex').slice(0, 12), name: repo?.name ?? (opts.url ? new URL(opts.url).hostname : undefined) },
+        // The ephemeral 127.0.0.1 address of a server samey started itself is not useful to report.
+        target: { path: repo?.root, url: opts.url ? displayUrl(opts.url) : undefined },
+        score,
+        categories,
+        findings: prioritize(all),
+        coverage,
+        versions: { scoring: SCORING.version, rules: ruleVersions(), model: coverage.model.enabled ? coverage.model.name : undefined },
+        viewports: crawlResult ? ['desktop', 'mobile'].map((name) => ({ name, width: VIEWPORTS[name].width, height: VIEWPORTS[name].height })) : [],
+        failedRoutes: pages
+            .filter((p) => !p.desktop)
+            .map((p) => ({ url: displayUrl(p.url), reason: p.error ?? (p.status ? `HTTP ${p.status}` : 'not rendered') })),
+        repo: repo ? { name: repo.name, frameworks: repo.frameworks, fileCount: repo.fileCount, truncated: repo.truncated } : undefined,
+        pages: pages.map((p) => ({
+            url: displayUrl(p.url),
+            path: p.path,
+            status: p.status,
+            error: p.error,
+            title: p.desktop?.title,
+            screenshots: Object.fromEntries(['desktop', 'mobile']
+                .filter((vp) => p[vp]?.screenshot)
+                .map((vp) => [vp, { file: `shots/${p[vp].screenshot}`, width: VIEWPORTS[vp].width, height: p[vp].screenshotHeight ?? 0 }])),
+        })),
+    };
+    const files = {};
+    // A ready-to-paste prompt for an AI coding agent, so fixing does not start with copying from the report.
+    const promptFile = path.join(outDir, 'fix-prompt.md');
+    const prompt = fullPrompt(report);
+    if (prompt) {
+        writeFileSync(promptFile, prompt);
+        files.prompt = promptFile;
+    }
+    else
+        rmSync(promptFile, { force: true });
+    if (opts.formats.includes('json')) {
+        files.json = path.join(outDir, 'report.json');
+        writeFileSync(files.json, JSON.stringify(report, null, 2));
+    }
+    if (opts.formats.includes('html')) {
+        files.html = path.join(outDir, 'report.html');
+        writeFileSync(files.html, renderHtml(report, outDir));
+    }
+    return { report, files, ruleErrors: errors };
+}
+function limitations(c, unmeasured) {
+    const out = [];
+    if (c.renderedNote)
+        out.push(c.renderedNote);
+    if (unmeasured.length)
+        out.push(`Not measured, so left out of the overall score: ${unmeasured.join(', ')}.`);
+    if (c.routeLimitHit)
+        out.push(`The route limit was reached; ${c.skipped.filter((s) => s.reason.startsWith('route limit')).length} discovered pages were not audited.`);
+    if (c.pagesFailed)
+        out.push(`${c.pagesFailed} page${c.pagesFailed === 1 ? '' : 's'} failed to load or returned an error status.`);
+    const robots = c.skipped.filter((s) => s.reason.includes('robots')).length;
+    if (robots)
+        out.push(`${robots} page${robots === 1 ? ' was' : 's were'} skipped because robots.txt disallows them.`);
+    if (c.blockedRequests.length)
+        out.push(`${c.blockedRequests.length}${c.blockedRequests.length === 20 ? '+' : ''} requests were blocked by the network policy (private, loopback, or unsupported addresses).`);
+    if (c.networkBudgetExceeded)
+        out.push('The crawl hit its network budget; some resources were not loaded.');
+    if (c.rendered)
+        out.push('Technical quality currently covers page metadata only; performance and asset weight are not measured yet.');
+    if (c.rendered && !c.interactions)
+        out.push('Button click testing was turned off.');
+    return out;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+import { Command, InvalidArgumentError, Option } from 'commander';
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import pc from 'picocolors';
+import { runAudit, toolVersion } from './audit.js';
+import { DEFAULTS, loadConfigFile } from './config.js';
+import { allRules } from './rules/index.js';
+import { fullPrompt } from './report/prompt.js';
+import { summarize } from './report/terminal.js';
+const int = (name, min = 1) => (v) => {
+    const n = Number(v);
+    if (!Number.isInteger(n) || n < min)
+        throw new InvalidArgumentError(`${name} must be an integer >= ${min}.`);
+    return n;
+};
+const program = new Command();
+program.name('samey').description('Lint your AI-built UI. Finds what looks generic, what is broken, and where to fix it.').version(toolVersion());
+program
+    .command('audit')
+    .description('Audit a local project, a URL, or both')
+    .argument('[path]', 'project directory to scan (and serve, if it has a static build)')
+    .option('-u, --url <url>', 'audit a running site at this URL')
+    .option('--serve [command]', 'start the project dev server with this command (default: npm run dev). Runs project code.')
+    .option('--dev', 'development mode: allow --url to point at localhost or a private network address')
+    .option('--port <port>', 'port the dev server listens on', int('port'), DEFAULTS.port)
+    .option('--max-routes <n>', 'maximum pages to render', int('max-routes'), DEFAULTS.maxRoutes)
+    .option('--timeout <seconds>', 'navigation timeout per page', int('timeout'), DEFAULTS.navTimeoutMs / 1000)
+    .option('--route <path...>', 'extra routes to audit, e.g. --route /pricing /about')
+    .addOption(new Option('--format <format>', 'report output').choices(['html', 'json', 'both']).default('both'))
+    .addOption(new Option('--report <format>', 'alias for --format').choices(['html', 'json', 'both']))
+    .option('-o, --out <dir>', 'output directory (default: <path>/.samey or ./.samey)')
+    .option('--static-only', 'skip rendering; only scan source files')
+    .option('--no-screenshots', 'do not capture screenshots')
+    .option('--no-interact', 'do not click any buttons')
+    .option('--ignore-robots', 'crawl pages disallowed by robots.txt (only for sites you own)')
+    .option('--ignore <rules...>', 'rule ids to skip')
+    .option('--fail-above <score>', 'exit with code 1 if the slop score is above this (0 = clean, 100 = worst)', int('fail-above', 0))
+    .option('--no-ai', 'never use a local model, even if one is configured')
+    .option('--model <name>', 'local Ollama vision model for an advisory critique, e.g. qwen2.5vl:7b')
+    .option('--model-endpoint <url>', 'local model server (loopback only)', DEFAULTS.modelEndpoint)
+    .option('--json', 'print the JSON report to stdout instead of the summary')
+    .option('-q, --quiet', 'only print the final summary')
+    .action(async (target, o) => {
+    const dir = target ? path.resolve(target) : undefined;
+    if (!dir && !o.url) {
+        program.error('Pass a project path, --url, or both. Example: samey audit . or samey audit --url https://example.com', { exitCode: 2 });
+    }
+    let file;
+    try {
+        file = loadConfigFile(dir);
+    }
+    catch (err) {
+        console.error(pc.red(err.message));
+        process.exit(2);
+    }
+    const src = (name) => program.commands[0].getOptionValueSource(name);
+    const pick = (cli, name, fromFile) => (src(name) === 'default' && fromFile !== undefined ? fromFile : cli);
+    // A dev-server command from the config file is only used when --serve is passed on the command line.
+    const serve = o.serve === true ? (file.serve ?? 'npm run dev') : typeof o.serve === 'string' ? o.serve : undefined;
+    const quiet = o.quiet || o.json;
+    const opts = {
+        ...DEFAULTS,
+        path: dir,
+        url: o.url,
+        serve,
+        dev: !!o.dev,
+        port: pick(o.port, 'port', file.port),
+        maxRoutes: pick(o.maxRoutes, 'maxRoutes', file.maxRoutes),
+        navTimeoutMs: src('timeout') === 'default' && file.navTimeoutMs ? file.navTimeoutMs : o.timeout * 1000,
+        pageTimeoutMs: file.pageTimeoutMs ?? DEFAULTS.pageTimeoutMs,
+        serverTimeoutMs: file.serverTimeoutMs ?? DEFAULTS.serverTimeoutMs,
+        outDir: o.out ? path.resolve(o.out) : path.join(dir ?? process.cwd(), '.samey'),
+        formats: (o.report ?? o.format) === 'both' ? ['html', 'json'] : [o.report ?? o.format],
+        screenshots: o.screenshots && file.screenshots !== false,
+        interact: o.interact && file.interact !== false,
+        staticOnly: !!o.staticOnly,
+        respectRobots: !o.ignoreRobots && file.respectRobots !== false,
+        ignoreRules: [...(file.ignoreRules ?? []), ...(o.ignore ?? [])],
+        routes: [...(file.routes ?? []), ...(o.route ?? [])],
+        failAbove: o.failAbove ?? file.failAbove,
+        ai: o.ai,
+        model: o.model ?? file.model,
+        modelEndpoint: pick(o.modelEndpoint, 'modelEndpoint', file.modelEndpoint),
+        modelTimeoutMs: DEFAULTS.modelTimeoutMs,
+        onProgress: quiet ? undefined : (m) => console.error(pc.dim(`  ${m}`)),
+    };
+    const unknownRules = opts.ignoreRules.filter((r) => !allRules.some((x) => x.id === r));
+    if (unknownRules.length)
+        console.error(pc.yellow(`  Unknown rule id${unknownRules.length > 1 ? 's' : ''} in ignore list: ${unknownRules.join(', ')}`));
+    try {
+        const { report, files, ruleErrors } = await runAudit(opts);
+        for (const e of ruleErrors)
+            console.error(pc.yellow(`  Rule ${e.ruleId} failed and was skipped: ${e.message}`));
+        if (o.json)
+            process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+        else
+            console.log(summarize(report, files));
+        if (report.coverage.renderAttempted && !report.coverage.rendered) {
+            console.error(pc.red(`  ${report.coverage.renderedNote}`));
+            process.exitCode = 2;
+            return;
+        }
+        if (opts.failAbove !== undefined) {
+            if (report.score === null) {
+                console.error(pc.red(`  --fail-above ${opts.failAbove}: nothing could be scored.`));
+                process.exitCode = 1;
+            }
+            else if (report.score > opts.failAbove) {
+                console.error(pc.red(`  Slop score ${report.score} is above --fail-above ${opts.failAbove}.`));
+                process.exitCode = 1;
+            }
+        }
+    }
+    catch (err) {
+        console.error(pc.red(`\n  Audit failed: ${err.message}\n`));
+        process.exitCode = 2;
+    }
+});
+program
+    .command('prompt')
+    .description('Print a fix prompt for an AI coding agent from the last audit')
+    .argument('[path]', 'project directory that was audited', '.')
+    .option('-o, --out <dir>', 'output directory used by the audit (default: <path>/.samey)')
+    .option('--only-defects', 'leave out design observations and include measured defects only')
+    .action((target, o) => {
+    const file = path.join(o.out ? path.resolve(o.out) : path.join(path.resolve(target), '.samey'), 'report.json');
+    let report;
+    try {
+        report = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        console.error(pc.red(`  No report at ${file}. Run \`npx samey-cli audit\` first.`));
+        process.exit(2);
+    }
+    const text = fullPrompt(report, { onlyDefects: !!o.onlyDefects });
+    if (!text) {
+        console.error('  The last audit found nothing to fix.');
+        return;
+    }
+    process.stdout.write(text);
+});
+program
+    .command('setup')
+    .description('Download the Chromium build that samey uses for rendered checks (about 150 MB, once)')
+    .action(() => {
+    // Use the Playwright version samey ships with, so the browser always matches it.
+    const require = createRequire(import.meta.url);
+    const cli = path.join(path.dirname(require.resolve('playwright/package.json')), 'cli.js');
+    const res = spawnSync(process.execPath, [cli, 'install', 'chromium'], { stdio: 'inherit' });
+    process.exitCode = res.status ?? 2;
+});
+program
+    .command('rules')
+    .description('List every rule samey runs')
+    .action(() => {
+    for (const r of allRules) {
+        console.log(`${pc.bold(r.id.padEnd(26))} ${pc.dim(`[${r.category}, ${r.needs}]`)}\n  ${r.description}`);
+    }
+});
+program.parseAsync().catch((err) => {
+    console.error(pc.red(err.message));
+    process.exit(2);
+});

package/dist/config.d.ts

@@ -0,0 +1,34 @@
+export interface AuditOptions {
+    /** Local project directory to analyze statically (and serve, if it has a static build). */
+    path?: string;
+    /** Rendered target. Overrides any local server. */
+    url?: string;
+    /** Shell command that starts a dev server. Passing it is the authorization to run project code. */
+    serve?: string;
+    /** Development mode: allows --url to point at loopback and private addresses. */
+    dev: boolean;
+    /** Test seam: replaces the network policy for the crawl. Never set from the CLI. */
+    policyOverride?: import('./security/net-policy.js').NetworkPolicy;
+    port: number;
+    maxRoutes: number;
+    navTimeoutMs: number;
+    pageTimeoutMs: number;
+    serverTimeoutMs: number;
+    outDir: string;
+    formats: ('html' | 'json')[];
+    screenshots: boolean;
+    interact: boolean;
+    staticOnly: boolean;
+    respectRobots: boolean;
+    ignoreRules: string[];
+    routes: string[];
+    /** Exit 1 when the slop score is above this. */
+    failAbove?: number;
+    ai: boolean;
+    model?: string;
+    modelEndpoint: string;
+    modelTimeoutMs: number;
+    onProgress?: (message: string) => void;
+}
+export declare const DEFAULTS: Omit<AuditOptions, 'outDir'>;
+export declare function loadConfigFile(dir: string | undefined): Partial<AuditOptions>;

package/dist/config.js

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+export const DEFAULTS = {
+    dev: false,
+    port: 4173,
+    maxRoutes: 10,
+    navTimeoutMs: 30_000,
+    pageTimeoutMs: 20_000,
+    serverTimeoutMs: 60_000,
+    formats: ['html', 'json'],
+    screenshots: true,
+    interact: true,
+    staticOnly: false,
+    respectRobots: true,
+    ignoreRules: [],
+    routes: [],
+    ai: true,
+    modelEndpoint: 'http://127.0.0.1:11434',
+    modelTimeoutMs: 120_000,
+};
+/** Keys accepted in samey.config.json. Anything else is rejected so typos surface. */
+const FILE_KEYS = new Set(['maxRoutes', 'navTimeoutMs', 'pageTimeoutMs', 'serverTimeoutMs', 'ignoreRules', 'routes', 'failAbove', 'model', 'modelEndpoint', 'serve', 'port', 'interact', 'respectRobots', 'screenshots']);
+export function loadConfigFile(dir) {
+    if (!dir)
+        return {};
+    const file = path.join(dir, 'samey.config.json');
+    if (!existsSync(file))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`Could not parse ${file}: ${err.message}`);
+    }
+    const unknown = Object.keys(parsed).filter((k) => !FILE_KEYS.has(k) && k !== '$schema');
+    if (unknown.length)
+        throw new Error(`Unknown key${unknown.length > 1 ? 's' : ''} in samey.config.json: ${unknown.join(', ')}`);
+    return parsed;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { runAudit, type AuditResult } from './audit.js';
+export { DEFAULTS, type AuditOptions } from './config.js';
+export { allRules, runRules } from './rules/index.js';
+export { scoreFindings, prioritize } from './score.js';
+export { scanRepo } from './static/scan.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { runAudit } from './audit.js';
+export { DEFAULTS } from './config.js';
+export { allRules, runRules } from './rules/index.js';
+export { scoreFindings, prioritize } from './score.js';
+export { scanRepo } from './static/scan.js';

package/dist/render/crawl.d.ts

@@ -0,0 +1,34 @@
+import type { Browser } from 'playwright';
+import { type NetworkPolicy } from '../security/net-policy.js';
+import type { CrawlResult, ViewportName } from '../types.js';
+import { type NetworkLimits } from './network.js';
+export interface CrawlOptions {
+    startUrl: string;
+    maxRoutes: number;
+    navTimeoutMs: number;
+    pageTimeoutMs: number;
+    seeds: string[];
+    shotsDir?: string;
+    interact: boolean;
+    respectRobots: boolean;
+    policy: NetworkPolicy;
+    limits?: NetworkLimits;
+    onProgress?: (message: string) => void;
+}
+export declare const VIEWPORTS: Record<ViewportName, {
+    width: number;
+    height: number;
+    isMobile: boolean;
+}>;
+export declare class BrowserMissingError extends Error {
+}
+/**
+ * In remote mode every request is served from Node by the network guard. Anything Chromium
+ * tries to send on its own (preconnects, WebRTC) is pointed at a closed local port so it
+ * cannot reach the network.
+ */
+export declare function launchBrowser(policy: NetworkPolicy): Promise<Browser>;
+/** Canonical key for a URL: origin + path without trailing slash, no query or hash. */
+export declare function urlKey(u: URL): string;
+export declare function normalizeLink(href: string, base: string): URL | null;
+export declare function crawl(browser: Browser, opts: CrawlOptions): Promise<CrawlResult>;