@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/screen-capture-provider.js

@@ -0,0 +1,218 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { applicationUrl } from './application-url.js';
+import { DoxloopError } from './errors.js';
+export const SCREEN_CAPTURE_SERVER = 'doxloop_capture';
+/** Launch the same Chrome channel used by the MCP server, then close it. */
+export async function checkScreenCaptureBrowser() {
+    try {
+        const chromium = await loadChromium();
+        const browser = await chromium.launch({ channel: 'chrome', headless: true, timeout: 15_000 });
+        await browser.close();
+        return { available: true, message: 'The Doxloop capture browser started successfully.' };
+    }
+    catch (cause) {
+        return {
+            available: false,
+            message: `The Doxloop capture browser could not start. Install Google Chrome and retry. ${cause instanceof Error ? cause.message.split('\n')[0] : String(cause)}`,
+        };
+    }
+}
+/** The Playwright bundled with the MCP server, so the sign-in window matches the capture browser. */
+async function loadChromium() {
+    const require = createRequire(import.meta.url);
+    const packageJson = require.resolve('@playwright/mcp/package.json');
+    const playwrightPath = createRequire(packageJson).resolve('playwright');
+    const imported = await import(pathToFileURL(playwrightPath).href);
+    const chromium = imported.chromium ?? imported.default?.chromium;
+    if (!chromium)
+        throw new Error('Playwright did not expose Chromium.');
+    return chromium;
+}
+/**
+ * Open a visible Chrome window on the application's sign-in page so the user
+ * can authenticate by hand, including MFA, SSO, and passkeys. The session is
+ * snapshotted every couple of seconds while the window is open, so closing
+ * the window early still leaves the last signed-in state to save.
+ */
+export async function startCaptureSignIn(application) {
+    const viewport = application.screenshots?.viewport ?? { width: 1440, height: 900 };
+    const path = application.authentication?.loginPath ?? application.screenshots?.startPath ?? application.readyPath ?? '/';
+    const url = applicationUrl(application.baseUrl, path).toString();
+    let chromium;
+    try {
+        chromium = await loadChromium();
+    }
+    catch (cause) {
+        throw new DoxloopError(`The sign-in browser could not load: ${cause instanceof Error ? cause.message.split('\n')[0] : String(cause)}`);
+    }
+    let browser;
+    try {
+        browser = await chromium.launch({ channel: 'chrome', headless: false, timeout: 20_000 });
+    }
+    catch (cause) {
+        throw new DoxloopError(`The sign-in browser could not start. Install Google Chrome and retry. ${cause instanceof Error ? cause.message.split('\n')[0] : String(cause)}`);
+    }
+    const context = await browser.newContext({ viewport });
+    const page = await context.newPage();
+    let latest;
+    let lastUrl = url;
+    let connected = true;
+    const snapshot = async () => {
+        if (!connected)
+            return latest;
+        try {
+            const pages = context.pages();
+            const active = pages[pages.length - 1];
+            if (active)
+                lastUrl = active.url();
+            latest = await context.storageState();
+        }
+        catch {
+            // The window is closing; keep the previous snapshot.
+        }
+        return latest;
+    };
+    const timer = setInterval(() => { void snapshot(); }, 2_000);
+    timer.unref?.();
+    browser.on('disconnected', () => {
+        connected = false;
+        clearInterval(timer);
+    });
+    const close = async () => {
+        clearInterval(timer);
+        if (!connected)
+            return;
+        connected = false;
+        try {
+            await browser.close();
+        }
+        catch { /* Already gone. */ }
+    };
+    try {
+        await page.goto(url, { waitUntil: 'commit', timeout: 30_000 });
+    }
+    catch (cause) {
+        await close();
+        throw new DoxloopError(`The sign-in page could not be opened: ${cause instanceof Error ? cause.message.split('\n')[0] : String(cause)}`);
+    }
+    return {
+        url,
+        currentUrl: () => lastUrl,
+        open: () => connected && browser.isConnected(),
+        state: snapshot,
+        finish: async () => {
+            const state = await snapshot();
+            await close();
+            if (!state)
+                throw new DoxloopError('The sign-in window closed before a session could be read. Start the sign-in again.');
+            return state;
+        },
+        cancel: close,
+    };
+}
+/**
+ * Build a private Playwright MCP server for one authoring run. The server is
+ * passed directly to the selected agent, so users do not have to install or
+ * configure a browser plugin in Codex or Claude Code themselves.
+ */
+export function screenCaptureProvider(workspace, application, auth, outputDirectory) {
+    const require = createRequire(import.meta.url);
+    const packageJson = require.resolve('@playwright/mcp/package.json');
+    const viewport = application.screenshots?.viewport ?? { width: 1440, height: 900 };
+    return {
+        name: SCREEN_CAPTURE_SERVER,
+        command: process.execPath,
+        args: [
+            join(dirname(packageJson), 'cli.js'),
+            '--headless',
+            '--browser',
+            'chrome',
+            '--isolated',
+            '--output-dir',
+            outputDirectory ?? join(resolve(workspace), '.doxloop', 'capture-output'),
+            '--viewport-size',
+            `${viewport.width}x${viewport.height}`,
+            '--timeout-action',
+            '10000',
+            '--timeout-navigation',
+            '60000',
+            // A recorded sign-in session seeds the isolated profile, so the agent
+            // lands on the signed-in application instead of its login page.
+            ...(auth?.storageStatePath ? ['--storage-state', auth.storageStatePath] : []),
+            // Saved credentials are typed by name: the agent passes the secret's
+            // name to the type or fill tool and the server substitutes the value,
+            // then redacts it from every tool response.
+            ...(auth?.secretsPath ? ['--secrets', auth.secretsPath] : []),
+        ],
+    };
+}
+export function codexCaptureArguments(provider, required) {
+    const prefix = `mcp_servers.${provider.name}`;
+    return [
+        '-c',
+        `${prefix}.command=${JSON.stringify(provider.command)}`,
+        '-c',
+        `${prefix}.args=${JSON.stringify(provider.args)}`,
+        '-c',
+        `${prefix}.startup_timeout_sec=20`,
+        '-c',
+        `${prefix}.required=${required}`,
+        '-c',
+        `${prefix}.default_tools_approval_mode="approve"`,
+    ];
+}
+export function claudeCaptureArguments(provider) {
+    return [
+        '--mcp-config',
+        JSON.stringify({
+            mcpServers: {
+                [provider.name]: {
+                    type: 'stdio',
+                    command: provider.command,
+                    args: provider.args,
+                },
+            },
+        }),
+    ];
+}
+/**
+ * Gemini CLI has no flag for a one-off MCP server: it reads `mcpServers` from
+ * the project's `.gemini/settings.json`. Merge the run's capture server into
+ * that file, keeping every other setting the user has there. `trust` lets the
+ * capture tools run without a confirmation Gemini cannot get unattended.
+ */
+export async function writeGeminiCaptureSettings(root, provider) {
+    const directory = join(root, '.gemini');
+    const path = join(directory, 'settings.json');
+    await mkdir(directory, { recursive: true });
+    let settings = {};
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            settings = parsed;
+    }
+    catch {
+        // A missing or unreadable file starts from an empty object.
+    }
+    const existing = settings.mcpServers;
+    const servers = existing && typeof existing === 'object' && !Array.isArray(existing) ? { ...existing } : {};
+    if (provider)
+        servers[provider.name] = geminiCaptureServer(provider);
+    else
+        delete servers[SCREEN_CAPTURE_SERVER];
+    settings.mcpServers = servers;
+    await writeFile(path, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+    return path;
+}
+export function geminiCaptureServer(provider) {
+    return {
+        command: provider.command,
+        args: provider.args,
+        timeout: 20_000,
+        trust: true,
+    };
+}
+//# sourceMappingURL=screen-capture-provider.js.map

package/dist/screenshot-workflow.d.ts

@@ -0,0 +1,167 @@
+import { PNG } from 'pngjs';
+import { type SignInProbe } from './application-probe.js';
+import { type CaptureAuthContext } from './capture-auth.js';
+import type { ApplicationConfig, DocumentationPlan, ScreenshotIntent, ScreenshotRunSummary } from './types.js';
+export declare const SCREENSHOT_MANIFEST_FILE: string;
+export interface ApplicationReadiness {
+    configured: boolean;
+    reachable: boolean;
+    status: 'not-configured' | 'ready' | 'authentication-required' | 'unreachable';
+    url?: string;
+    message: string;
+    /**
+     * How sign-in will be handled during capture: the recorded browser session,
+     * saved credentials the agent types, an expired session with nothing to
+     * fall back on, or no sign-in material at all.
+     */
+    authentication?: 'none' | 'session' | 'credentials' | 'expired';
+    /**
+     * The sign-in route a browser visit ended on, when the page is a sign-in
+     * wall that only shows once client-side routing runs (a single-page app
+     * that answers 200 and then redirects to `/auth`).
+     */
+    signInPath?: string;
+}
+export interface ApplicationReadinessOptions {
+    /**
+     * Load the page in the headless browser when the HTTP check says it is
+     * ready and no sign-in material exists, to catch client-side sign-in walls.
+     * `true` uses the managed browser; a function replaces it (tests).
+     */
+    browserProbe?: boolean | SignInProbe;
+    /** Where the message is shown: the setup wizard or a project's settings. */
+    context?: 'setup' | 'project';
+}
+/** The message for a sign-in wall the browser probe found. */
+export declare function signInWallMessage(signInPath: string, context?: 'setup' | 'project'): string;
+interface ScreenshotManifest {
+    schemaVersion: 1;
+    guides: ScreenshotManifestGuide[];
+}
+interface ScreenshotManifestGuide {
+    page: string;
+    steps: ScreenshotManifestStep[];
+}
+interface ScreenshotManifestStep {
+    id: string;
+    action: string;
+    expectedState: string;
+    purpose: string;
+    /** One-based item in the approved page visuals.captureSequence. */
+    sequenceItem?: number;
+    capture: boolean | 'required' | 'recommended';
+    target?: string;
+    file?: string;
+    alt?: string;
+    /** `planned` is the staged, not-yet-attempted state Doxloop writes up front. */
+    status: 'planned' | 'verified' | 'text-only' | 'failed';
+    textOnlyReason?: string;
+    checks?: {
+        expectedStateConfirmed?: boolean;
+        privacyReviewed?: boolean;
+        legibilityReviewed?: boolean;
+        meaningful?: boolean;
+    };
+}
+/** Generator-native committed asset root for guide screenshots. */
+export declare const GUIDE_ASSET_ROOTS: Record<string, string>;
+/**
+ * Create the guide asset directories before the agent opens a browser.
+ *
+ * The capture tool resolves its filename against the project root and does not
+ * create missing parents: a nested filename whose directory does not exist
+ * fails with ENOENT, and the run then reports screenshots it never took. The
+ * agent is told to create each directory, but a forgotten `mkdir` silently
+ * costs an entire guide, so Doxloop creates the predictable ones itself.
+ */
+export declare function prepareGuideAssetDirectories(workspace: string, generator: string, plan: Pick<DocumentationPlan, 'pages'> | undefined, contentDir?: string): Promise<string[]>;
+/**
+ * Write the approved guides into the manifest before the agent runs.
+ *
+ * Left to build the manifest itself, an agent builds it at the end out of what
+ * it happened to capture: guides it decided to skip — often without ever
+ * opening their startPath — simply do not appear, and the run reports success
+ * while quietly dropping half the approved work. Staging every approved guide
+ * up front turns capture into filling in a form, and a guide the agent never
+ * touched stays visible as an unfinished row instead of vanishing.
+ *
+ * Existing manifests are never overwritten, so a resumed or recovered run keeps
+ * the work it already recorded.
+ */
+export declare function writeScreenshotManifestSkeleton(workspace: string, plan: Pick<DocumentationPlan, 'pages'> | undefined): Promise<number>;
+/**
+ * Claim images the agent captured but never recorded as captures.
+ *
+ * An agent cannot see a PNG file, so any manifest row it fills in is bookkeeping
+ * rather than observation. A cautious agent that is asked to inspect the saved
+ * image concludes it cannot, and honestly records every step as text-only —
+ * discarding a directory of perfectly good screenshots and failing a run that
+ * actually worked. The state was already confirmed in the browser before the
+ * shutter, and Doxloop checks the file itself during validation, so adopt an
+ * unclaimed image into the step its filename names and let that validation
+ * judge it. The images are surfaced for human review either way.
+ */
+export declare function adoptCapturedImages(workspace: string, generator: string, plan: DocumentationPlan | undefined): Promise<string[]>;
+export declare function collapseDuplicateCaptures(workspace: string, plan: DocumentationPlan | undefined): Promise<string[]>;
+/** Drop an image reference, and the frame wrapper it leaves behind. */
+export declare function removeImageReference(content: string, file: string): string;
+/**
+ * Place verified captures the agent left orphaned.
+ *
+ * Agents routinely capture every planned state and then embed only the first,
+ * because a step component holds the procedure and there is no obvious place to
+ * put the rest. The images are real and reviewed, so dropping the run over
+ * placement wastes correct work: insert each unused capture into the step it
+ * belongs to, matching capture order to step order, and fall back to the end of
+ * the page when the guide has no step markup.
+ */
+export declare function embedMissingCaptures(workspace: string, plan: DocumentationPlan | undefined): Promise<string[]>;
+export declare function normalizeScreenshotIntent(value: unknown): ScreenshotIntent;
+export declare function assertScreenshotPlanningReadiness(application: ApplicationConfig | undefined, rawIntent: unknown, auth?: CaptureAuthContext): Promise<void>;
+export declare function screenshotPlanSummary(plan: Pick<DocumentationPlan, 'pages'>): {
+    guides: number;
+    captures: number;
+};
+export declare function checkApplicationReadiness(application?: ApplicationConfig, auth?: CaptureAuthContext, options?: ApplicationReadinessOptions): Promise<ApplicationReadiness>;
+export interface ScreenshotValidationOptions {
+    /**
+     * Accept the run despite screenshot problems. Every defect becomes a text-only
+     * step with the problem recorded as its reason, images that cannot be shown
+     * are removed from their guide, and the summary reports how many problems
+     * remain for review. Nothing is thrown for a capture shortfall.
+     */
+    tolerateDefects?: boolean;
+    /**
+     * Collect every defect without changing the manifest, the pages, or the
+     * images, so a targeted retake can be attempted before anything is
+     * downgraded. Implies `tolerateDefects` for collection purposes.
+     */
+    dryRun?: boolean;
+}
+export declare function validateScreenshotManifest(workspace: string, plan: DocumentationPlan | undefined, rawIntent: unknown, options?: ScreenshotValidationOptions): Promise<{
+    summary: ScreenshotRunSummary;
+    manifest?: ScreenshotManifest;
+    defects: string[];
+}>;
+/**
+ * Summarize how far capture got, guide by guide, for an agent that continues an
+ * interrupted run. Verified rows are named so the agent keeps them; unfinished
+ * rows are named with their start path so it knows exactly what is left.
+ */
+export declare function describeScreenshotManifestProgress(workspace: string, plan: DocumentationPlan | undefined): Promise<{
+    lines: string[];
+    verified: number;
+    unfinished: number;
+}>;
+/** Share of sampled pixels holding the single most common color. */
+export declare function dominantColorShare(image: PNG): number;
+/** Where a run's discarded images go; never part of a proposal, always recoverable. */
+export declare const QUARANTINE_DIRECTORY = ".doxloop/quarantine";
+/**
+ * Set an image aside instead of deleting it. A downgrade that turns out to be
+ * wrong (a validator disagreeing with bookkeeping, a duplicate that was not
+ * one) then costs a note on the run, not the picture.
+ */
+export declare function quarantineImage(workspace: string, file: string): Promise<string | undefined>;
+export {};
+//# sourceMappingURL=screenshot-workflow.d.ts.map