agentscreenshots 0.1.0

package/dist/feedback.js

@@ -0,0 +1,35 @@
+import { resolveApiUrl, resolveLicenseKey } from './config.js';
+export async function sendFeedback(options) {
+    const apiUrl = await resolveApiUrl(options.apiUrl);
+    const licenseKey = await resolveLicenseKey(options.licenseKey);
+    const headers = {
+        'content-type': 'application/json'
+    };
+    if (licenseKey) {
+        headers.authorization = `Bearer ${licenseKey}`;
+    }
+    const response = await fetch(`${apiUrl}/api/cli/feedback`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+            kind: options.kind,
+            message: options.message,
+            metadata: {
+                cliVersion: options.cliVersion,
+                nodeVersion: process.versions.node,
+                platform: process.platform,
+                arch: process.arch,
+                apiUrl,
+                licenseKeyConfigured: Boolean(licenseKey)
+            }
+        })
+    });
+    const body = await response.json().catch(() => null);
+    if (!response.ok) {
+        const error = body && typeof body === 'object' && 'error' in body
+            ? String(body.error)
+            : `HTTP ${response.status}`;
+        throw new Error(`Feedback failed: ${error}`);
+    }
+    return body;
+}

package/dist/index.js

@@ -0,0 +1,503 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { capture } from './capture.js';
+import { clearLicenseKey, readConfig, writeConfig } from './config.js';
+import { runDoctor } from './doctor.js';
+import { sendFeedback } from './feedback.js';
+import { validateLicense } from './reporting.js';
+function printHelp() {
+    console.log(`agentshot
+
+Usage:
+  agentshot URL OUTPUT [options]
+  agentshot auth LICENSE_KEY [--api-url URL] [--json]
+  agentshot status [--api-url URL] [--license-key KEY]
+  agentshot doctor [--api-url URL] [--license-key KEY]
+  agentshot feedback "MESSAGE" [--kind feedback|bug|idea]
+  agentshot logout
+
+Examples:
+  agentshot "http://127.0.0.1:5200/design" "./shots/design.png"
+  agentshot "http://127.0.0.1:5200/design" "./shots/hero.png" --height 1200
+  agentshot "http://127.0.0.1:5200/design" "./shots/cards.png" --from 1800 --to 2500
+  agentshot "http://127.0.0.1:5200/design" "./shots/borders.png" --selector "section:has-text('Borders')" --padding 24
+  agentshot "http://127.0.0.1:5200/design" "./shots/page.png" --scroll --wait 1000
+
+Capture options:
+  --wait MS                 Wait after load/scroll before capture
+  --scroll                  Scroll through the page first to trigger lazy-loaded content
+  --selector SELECTOR       Capture the first matching Playwright/CSS selector
+  --section SELECTOR        Alias for --selector
+  --nth INDEX               Capture selector match by zero-based index (default: 0)
+  --padding PX              Add padding around selector screenshots (default: 0)
+  --height PX               Capture from --from/top to this height; defaults from 0
+  --from PX                 Vertical crop start, page pixels
+  --to PX                   Vertical crop end, page pixels
+  --width PX                Browser viewport width (default: 1280)
+  --viewport-height PX      Browser viewport height (default: 900)
+  --viewport WIDTHxHEIGHT   Set viewport width and height together
+  --wait-for CSS            Wait for a selector before capture
+  --wait-until STATE        load, domcontentloaded, or networkidle (default: load)
+  --timeout MS              Navigation/action timeout (default: 30000)
+  --browser NAME            chromium or chrome (default: chromium)
+  --headed                  Show the browser window
+  --no-full-page            Capture only viewport when no selector/crop is used
+  --device-scale-factor N   Device scale factor (default: 1)
+  --json                    Print machine-readable JSON
+  --no-report               Do not report a visual check to AgentScreenshots
+  --api-url URL             Override AgentScreenshots API URL
+  --license-key KEY         Override configured license key
+
+Environment:
+  AGENTSHOT_API_URL
+  AGENTSHOT_LICENSE_KEY
+  AGENTSHOT_CONFIG
+`);
+}
+function parsePositiveNumber(value, name) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`${name} must be a positive number.`);
+    }
+    return parsed;
+}
+function parseInteger(value, name) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`${name} must be a positive integer.`);
+    }
+    return parsed;
+}
+function readValue(args, index, option) {
+    const value = args[index + 1];
+    if (!value || value.startsWith('--')) {
+        throw new Error(`${option} requires a value.`);
+    }
+    return value;
+}
+function getDefaultCaptureOptions(url, output) {
+    return {
+        url,
+        output,
+        width: 1280,
+        viewportHeight: 900,
+        deviceScaleFactor: 1,
+        waitMs: 0,
+        timeoutMs: 30_000,
+        scroll: false,
+        selector: null,
+        selectorIndex: 0,
+        padding: 0,
+        fromY: null,
+        toY: null,
+        clipHeight: null,
+        fullPage: true,
+        waitForSelector: null,
+        waitForLoadState: 'load',
+        browser: 'chromium',
+        headed: false,
+        json: false,
+        report: true,
+        apiUrl: null,
+        licenseKey: null
+    };
+}
+function parseCommonAuthOptions(args, startIndex = 0) {
+    let apiUrl = null;
+    let licenseKey = null;
+    let json = false;
+    for (let index = startIndex; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--api-url') {
+            apiUrl = readValue(args, index, arg);
+            index += 1;
+        }
+        else if (arg === '--license-key') {
+            licenseKey = readValue(args, index, arg);
+            index += 1;
+        }
+        else if (arg === '--json') {
+            json = true;
+        }
+        else {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    return { apiUrl, licenseKey, json };
+}
+function parseFeedback(args) {
+    const messageParts = [];
+    let kind = 'feedback';
+    let apiUrl = null;
+    let licenseKey = null;
+    let json = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--kind') {
+            const value = readValue(args, index, arg);
+            if (value !== 'feedback' && value !== 'bug' && value !== 'idea') {
+                throw new Error('--kind must be feedback, bug, or idea.');
+            }
+            kind = value;
+            index += 1;
+        }
+        else if (arg === '--api-url') {
+            apiUrl = readValue(args, index, arg);
+            index += 1;
+        }
+        else if (arg === '--license-key') {
+            licenseKey = readValue(args, index, arg);
+            index += 1;
+        }
+        else if (arg === '--json') {
+            json = true;
+        }
+        else if (arg.startsWith('--')) {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+        else {
+            messageParts.push(arg);
+        }
+    }
+    const message = messageParts.join(' ').trim();
+    if (!message) {
+        throw new Error('Usage: agentshot feedback "MESSAGE" [--kind feedback|bug|idea]');
+    }
+    return {
+        name: 'feedback',
+        kind,
+        message,
+        apiUrl,
+        licenseKey,
+        json
+    };
+}
+function parseLogout(args) {
+    let json = false;
+    for (const arg of args) {
+        if (arg === '--json') {
+            json = true;
+        }
+        else {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    return { name: 'logout', json };
+}
+function parseCapture(args) {
+    if (args.length < 2) {
+        throw new Error('Capture requires URL and OUTPUT.');
+    }
+    const [url, output, ...rest] = args;
+    const options = getDefaultCaptureOptions(url, output);
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        switch (arg) {
+            case '--wait':
+                options.waitMs = parseInteger(readValue(rest, index, arg), arg);
+                index += 1;
+                break;
+            case '--scroll':
+                options.scroll = true;
+                break;
+            case '--selector':
+            case '--section':
+                options.selector = readValue(rest, index, arg);
+                index += 1;
+                break;
+            case '--nth':
+                options.selectorIndex = parseInteger(readValue(rest, index, arg), arg);
+                index += 1;
+                break;
+            case '--padding':
+                options.padding = parseInteger(readValue(rest, index, arg), arg);
+                index += 1;
+                break;
+            case '--height':
+                options.clipHeight = parseInteger(readValue(rest, index, arg), arg);
+                index += 1;
+                break;
+            case '--from':
+                options.fromY = parseInteger(readValue(rest, index, arg), arg);
+                index += 1;
+                break;
+            case '--to':
+                options.toY = parseInteger(readValue(rest, index, arg), arg);
+                index += 1;
+                break;
+            case '--width':
+                options.width = parseInteger(readValue(rest, index, arg), arg);
+                index += 1;
+                break;
+            case '--viewport-height':
+                options.viewportHeight = parseInteger(readValue(rest, index, arg), arg);
+                index += 1;
+                break;
+            case '--viewport': {
+                const value = readValue(rest, index, arg);
+                const match = value.match(/^(\d+)x(\d+)$/i);
+                if (!match) {
+                    throw new Error('--viewport must look like 1280x900.');
+                }
+                options.width = parseInteger(match[1], '--viewport width');
+                options.viewportHeight = parseInteger(match[2], '--viewport height');
+                index += 1;
+                break;
+            }
+            case '--wait-for':
+                options.waitForSelector = readValue(rest, index, arg);
+                index += 1;
+                break;
+            case '--wait-until': {
+                const value = readValue(rest, index, arg);
+                if (value !== 'load' && value !== 'domcontentloaded' && value !== 'networkidle') {
+                    throw new Error('--wait-until must be load, domcontentloaded, or networkidle.');
+                }
+                options.waitForLoadState = value;
+                index += 1;
+                break;
+            }
+            case '--timeout':
+                options.timeoutMs = parseInteger(readValue(rest, index, arg), arg);
+                index += 1;
+                break;
+            case '--browser': {
+                const value = readValue(rest, index, arg);
+                if (value !== 'chromium' && value !== 'chrome') {
+                    throw new Error('--browser must be chromium or chrome.');
+                }
+                options.browser = value;
+                index += 1;
+                break;
+            }
+            case '--headed':
+                options.headed = true;
+                break;
+            case '--no-full-page':
+                options.fullPage = false;
+                break;
+            case '--device-scale-factor':
+                options.deviceScaleFactor = parsePositiveNumber(readValue(rest, index, arg), arg);
+                index += 1;
+                break;
+            case '--json':
+                options.json = true;
+                break;
+            case '--no-report':
+                options.report = false;
+                break;
+            case '--api-url':
+                options.apiUrl = readValue(rest, index, arg);
+                index += 1;
+                break;
+            case '--license-key':
+                options.licenseKey = readValue(rest, index, arg);
+                index += 1;
+                break;
+            default:
+                throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    return { name: 'capture', options };
+}
+function parseArgs(args) {
+    const first = args[0];
+    if (!first || first === '--help' || first === '-h' || first === 'help') {
+        return { name: 'help' };
+    }
+    if (first === '--version' || first === '-v' || first === 'version') {
+        return { name: 'version' };
+    }
+    if (first === 'auth') {
+        const key = args[1];
+        if (!key || key.startsWith('--')) {
+            throw new Error('Usage: agentshot auth LICENSE_KEY [--api-url URL]');
+        }
+        const { apiUrl, json } = parseCommonAuthOptions(args, 2);
+        return { name: 'auth', key, apiUrl, json };
+    }
+    if (first === 'status') {
+        return { name: 'status', ...parseCommonAuthOptions(args, 1) };
+    }
+    if (first === 'doctor') {
+        return { name: 'doctor', ...parseCommonAuthOptions(args, 1) };
+    }
+    if (first === 'feedback') {
+        return parseFeedback(args.slice(1));
+    }
+    if (first === 'logout') {
+        return parseLogout(args.slice(1));
+    }
+    return parseCapture(args);
+}
+async function readPackageVersion() {
+    const currentFile = fileURLToPath(import.meta.url);
+    const packageJsonPath = join(dirname(currentFile), '..', 'package.json');
+    try {
+        const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8'));
+        return packageJson.version ?? '0.1.0';
+    }
+    catch {
+        return '0.1.0';
+    }
+}
+async function run() {
+    const command = parseArgs(process.argv.slice(2));
+    if (command.name === 'help') {
+        printHelp();
+        return;
+    }
+    if (command.name === 'version') {
+        console.log(await readPackageVersion());
+        return;
+    }
+    if (command.name === 'auth') {
+        const config = await readConfig();
+        const apiUrl = command.apiUrl ?? config.apiUrl;
+        const validation = await validateLicense({
+            apiUrl,
+            licenseKey: command.key
+        });
+        if (!validation.ok) {
+            if (command.json) {
+                console.log(JSON.stringify(validation.body, null, 2));
+            }
+            else {
+                console.error(`License validation failed (${validation.status}).`);
+                if (validation.body) {
+                    console.error(JSON.stringify(validation.body, null, 2));
+                }
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const path = await writeConfig({
+            ...config,
+            apiUrl,
+            licenseKey: command.key
+        });
+        if (command.json) {
+            console.log(JSON.stringify({
+                ok: true,
+                path,
+                license: validation.body?.license
+            }, null, 2));
+        }
+        else {
+            const license = validation.body?.license;
+            console.log(`Saved license key to ${path}`);
+            console.log(`License ${license?.keyPrefix ?? ''} valid: ${license?.usedChecks ?? 0}/${license?.quotaChecks ?? 0} checks used`);
+        }
+        return;
+    }
+    if (command.name === 'logout') {
+        const result = await clearLicenseKey();
+        if (command.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else if (result.hadLicenseKey) {
+            console.log(`Removed saved license key from ${result.path}`);
+        }
+        else {
+            console.log(`No saved license key found in ${result.path}`);
+        }
+        if (result.envOverrideActive && !command.json) {
+            console.error('AGENTSHOT_LICENSE_KEY is still set in the environment.');
+        }
+        return;
+    }
+    if (command.name === 'status') {
+        let result;
+        try {
+            result = await validateLicense({
+                apiUrl: command.apiUrl,
+                licenseKey: command.licenseKey
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (command.json) {
+                console.log(JSON.stringify({
+                    ok: false,
+                    reason: 'no_license_key',
+                    message
+                }, null, 2));
+            }
+            else {
+                console.error(message);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        if (command.json) {
+            console.log(JSON.stringify(result.body, null, 2));
+        }
+        else if (result.ok) {
+            const license = result.body?.license;
+            console.log(`License ${license?.keyPrefix ?? ''} valid: ${license?.usedChecks ?? 0}/${license?.quotaChecks ?? 0} checks used`);
+        }
+        else {
+            console.error(`License check failed (${result.status}).`);
+            if (result.body) {
+                console.error(JSON.stringify(result.body, null, 2));
+            }
+            process.exitCode = 1;
+        }
+        return;
+    }
+    if (command.name === 'doctor') {
+        const result = await runDoctor(command);
+        if (command.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(`agentshot doctor: ${result.status}`);
+            for (const check of result.checks) {
+                console.log(`${check.status.padEnd(4)} ${check.name}: ${check.message}`);
+            }
+        }
+        if (result.status === 'fail') {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    if (command.name === 'feedback') {
+        const result = await sendFeedback({
+            apiUrl: command.apiUrl,
+            licenseKey: command.licenseKey,
+            json: command.json,
+            kind: command.kind,
+            message: command.message,
+            cliVersion: await readPackageVersion()
+        });
+        if (command.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            const feedback = result?.feedback;
+            console.log(`Feedback sent${feedback?.id ? ` (${feedback.id})` : ''}.`);
+        }
+        return;
+    }
+    const result = await capture(command.options);
+    if (command.options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`Captured ${result.width}x${result.height} -> ${result.output} (${(result.durationMs / 1000).toFixed(1)}s)`);
+    if (result.reportStatus === 'failed') {
+        console.error(`Usage report failed: ${result.reportReason}`);
+    }
+    else if (result.reportStatus === 'queued') {
+        console.error(`Usage report queued for retry: ${result.reportReason}`);
+    }
+    else if (result.reportStatus === 'skipped' && result.reportReason === 'no_license_key') {
+        console.error('Usage report skipped: no license key configured.');
+    }
+}
+run().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/reporting.js

@@ -0,0 +1,169 @@
+import { appendFile, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { getConfigPath, resolveApiUrl, resolveLicenseKey } from './config.js';
+export async function getFileSize(path) {
+    const file = await stat(path);
+    return file.size;
+}
+export function getTargetKind(url) {
+    try {
+        const parsed = new URL(url);
+        const hostname = parsed.hostname.toLowerCase();
+        if (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1') {
+            return 'localhost';
+        }
+    }
+    catch {
+        return 'localhost';
+    }
+    return 'public';
+}
+function getQueuePath() {
+    return join(dirname(getConfigPath()), 'usage-queue.jsonl');
+}
+async function readQueuedEvents() {
+    const path = getQueuePath();
+    try {
+        const content = await readFile(path, 'utf8');
+        return content
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+async function writeQueuedEvents(events) {
+    const path = getQueuePath();
+    if (events.length === 0) {
+        await rm(path, { force: true });
+        return;
+    }
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${events.map((event) => JSON.stringify(event)).join('\n')}\n`, {
+        mode: 0o600
+    });
+}
+async function queueUsageEvent(event) {
+    const path = getQueuePath();
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await appendFile(path, `${JSON.stringify({ ...event, queuedAt: event.queuedAt ?? new Date().toISOString() })}\n`, { mode: 0o600 });
+}
+async function postUsageEvent(apiUrl, licenseKey, event) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 4_000);
+    try {
+        const response = await fetch(`${apiUrl}/api/cli/report-check`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${licenseKey}`,
+                'content-type': 'application/json'
+            },
+            body: JSON.stringify({
+                eventId: event.eventId,
+                metadata: event.metadata
+            }),
+            signal: controller.signal
+        });
+        const payload = (await response.json().catch(() => null));
+        const reason = payload?.reason ?? `http_${response.status}`;
+        if (response.ok) {
+            return { ok: true, retryable: false, reason };
+        }
+        return {
+            ok: false,
+            retryable: response.status >= 500 || response.status === 429,
+            reason
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function flushQueuedEvents(apiUrl, licenseKey) {
+    const queued = await readQueuedEvents();
+    if (queued.length === 0) {
+        return { flushed: 0, kept: 0 };
+    }
+    const remaining = [];
+    let flushed = 0;
+    for (const event of queued) {
+        try {
+            const result = await postUsageEvent(apiUrl, licenseKey, event);
+            if (result.ok || !result.retryable) {
+                flushed += 1;
+                continue;
+            }
+            remaining.push(event);
+        }
+        catch {
+            remaining.push(event);
+        }
+    }
+    await writeQueuedEvents(remaining);
+    return {
+        flushed,
+        kept: remaining.length
+    };
+}
+export async function reportCheck(options) {
+    const licenseKey = await resolveLicenseKey(options.licenseKey);
+    if (!licenseKey) {
+        return {
+            reported: false,
+            status: 'skipped',
+            reason: 'no_license_key'
+        };
+    }
+    const apiUrl = await resolveApiUrl(options.apiUrl);
+    const event = {
+        eventId: crypto.randomUUID(),
+        metadata: options.metadata
+    };
+    try {
+        await flushQueuedEvents(apiUrl, licenseKey);
+        const result = await postUsageEvent(apiUrl, licenseKey, event);
+        if (!result.ok) {
+            return {
+                reported: false,
+                status: 'failed',
+                reason: result.reason
+            };
+        }
+        return {
+            reported: true,
+            status: 'ok',
+            reason: result.reason
+        };
+    }
+    catch (error) {
+        await queueUsageEvent(event);
+        return {
+            reported: false,
+            status: 'queued',
+            reason: error instanceof Error ? error.message : 'queued_for_retry'
+        };
+    }
+}
+export async function validateLicense(options) {
+    const licenseKey = await resolveLicenseKey(options.licenseKey);
+    if (!licenseKey) {
+        throw new Error('No license key configured. Run `agentshot auth ags_live_...` first.');
+    }
+    const apiUrl = await resolveApiUrl(options.apiUrl);
+    const response = await fetch(`${apiUrl}/api/cli/license`, {
+        headers: {
+            authorization: `Bearer ${licenseKey}`
+        }
+    });
+    return {
+        ok: response.ok,
+        status: response.status,
+        body: await response.json().catch(() => null)
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};