@doxbrix/doxloop 0.1.5 → 0.2.0

package/dist/branding.js

@@ -0,0 +1,229 @@
+import { createHash } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { listAssets } from './assets.js';
+import { applyDirectEdit } from './direct-edit.js';
+import { DoxloopError } from './errors.js';
+import { resolveContainedDirectory } from './fs.js';
+import { loadGeneratorAdapter } from './generators.js';
+import { loadProject, loadSiteConfig, relativePath, siteConfigPath } from './project.js';
+import { validateDoxbrixTheme } from './validation.js';
+/**
+ * The branding panel edits the Doxbrix theme block of `docs.json`: logos,
+ * favicon, accent colours for light and dark, page backgrounds, colour mode,
+ * and fonts. The preview reads `docs.json` on every request, so a saved
+ * change shows up on the next reload without a build. External generators
+ * keep their own theme configuration; the panel names the file instead.
+ */
+export const THEME_COLOR_FIELDS = ['primaryColor', 'lightColor', 'darkColor', 'backgroundColorLight', 'backgroundColorDark'];
+export const THEME_FONT_FIELDS = ['font', 'headingFont', 'codeFont'];
+export const THEME_ASSET_FIELDS = ['logoLight', 'logoDark', 'favicon', 'faviconLight', 'faviconDark', 'backgroundImage'];
+export const THEME_MODES = ['light', 'dark', 'system'];
+export const THEME_CODE_THEMES = ['auto', 'light', 'dark'];
+const THEME_FIELDS = [...THEME_COLOR_FIELDS, ...THEME_FONT_FIELDS, ...THEME_ASSET_FIELDS, 'mode', 'codeTheme', 'logoHref'];
+/** Where each external generator keeps the settings a branding panel would edit. */
+const THEME_CONFIG_FILES = {
+    docusaurus: 'docusaurus.config.js',
+    mkdocs: 'mkdocs.yml',
+    sphinx: 'conf.py',
+    hugo: 'hugo.toml',
+    vitepress: '.vitepress/config.mts',
+    markdoc: 'markdoc.config.mjs',
+    nextra: 'theme.config.tsx',
+    starlight: 'astro.config.mjs',
+    jekyll: '_config.yml',
+    static: 'assets/styles.css',
+};
+export async function readBranding(root) {
+    const project = await loadProject(root);
+    if (project.generator !== 'doxbrix') {
+        const adapter = await loadGeneratorAdapter(root, project);
+        const configFile = adapter.theme?.configFile ?? THEME_CONFIG_FILES[project.generator] ?? adapter.planning?.navigationFiles[0] ?? '';
+        return {
+            generator: project.generator,
+            editable: false,
+            reason: `${adapter.displayName} keeps its logo, colours, and fonts in ${configFile || 'its own configuration'}. Edit that file directly, or ask the agent to apply the branding.`,
+            configFile,
+            fingerprint: '',
+            site: { name: project.title, description: '' },
+            theme: {},
+            assets: [],
+        };
+    }
+    const configPath = await siteConfigPath(root, project);
+    const raw = await readFile(configPath, 'utf8');
+    const site = await loadSiteConfig(root, project);
+    const theme = themeObject(site.theme);
+    const values = {};
+    for (const field of THEME_FIELDS) {
+        const value = theme[field];
+        if (typeof value === 'string' && value.trim())
+            values[field] = value.trim();
+    }
+    const assets = (await listAssets(root)).filter((asset) => asset.kind === 'image').map((asset) => ({
+        path: asset.path,
+        name: asset.name,
+        publicPath: asset.publicPath,
+    }));
+    return {
+        generator: 'doxbrix',
+        editable: true,
+        configFile: relativePath(root, configPath),
+        fingerprint: fingerprint(raw),
+        site: { name: site.name ?? project.title, description: site.description ?? '' },
+        theme: values,
+        assets,
+    };
+}
+export async function writeBranding(root, raw) {
+    const input = parseWrite(raw);
+    const current = await readBranding(root);
+    if (!current.editable)
+        throw new DoxloopError(current.reason ?? 'Branding cannot be edited from Doxloop for this generator.', 2);
+    if (input.fingerprint !== current.fingerprint) {
+        throw new DoxloopError('The site configuration changed on disk since it was loaded. Reload the branding panel and apply your changes again.');
+    }
+    const project = await loadProject(root);
+    const configPath = await siteConfigPath(root, project);
+    const site = await loadSiteConfig(root, project);
+    const theme = themeObject(site.theme);
+    for (const [field, value] of Object.entries(input.theme ?? {})) {
+        if (value === null || value === '')
+            delete theme[field];
+        else
+            theme[field] = value;
+    }
+    const name = input.site?.name !== undefined ? input.site.name.trim() : site.name;
+    const description = input.site?.description !== undefined ? input.site.description.trim() : site.description;
+    if (input.site?.name !== undefined && !name)
+        throw new DoxloopError('Site name cannot be empty.', 2);
+    const contentRoot = await resolveContainedDirectory(root, project.contentDir, 'Documentation content directory', { allowRoot: true });
+    const issues = [];
+    await validateDoxbrixTheme(theme, contentRoot, current.configFile, issues);
+    const errors = issues.filter((issue) => issue.severity === 'error');
+    if (errors.length > 0)
+        throw new DoxloopError(errors.map((issue) => issue.message).join(' '), 2);
+    const next = {
+        ...site,
+        ...(name ? { name } : {}),
+        ...(description ? { description } : {}),
+        ...(Object.keys(theme).length > 0 ? { theme } : {}),
+    };
+    if (!description)
+        delete next.description;
+    if (Object.keys(theme).length === 0)
+        delete next.theme;
+    await applyDirectEdit(root, {
+        kind: 'branding',
+        requestText: describeChange(input, project),
+        files: [current.configFile],
+        apply: () => writeFile(configPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8'),
+    });
+    return readBranding(root);
+}
+function parseWrite(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        throw new DoxloopError('A branding write needs a fingerprint and the fields to change.', 2);
+    const body = raw;
+    if (typeof body.fingerprint !== 'string')
+        throw new DoxloopError('A branding write needs the fingerprint it was loaded with.', 2);
+    const result = { fingerprint: body.fingerprint };
+    if (body.site !== undefined) {
+        const site = (body.site && typeof body.site === 'object' ? body.site : {});
+        result.site = {};
+        if (site.name !== undefined)
+            result.site.name = textOrThrow(site.name, 'Site name');
+        if (site.description !== undefined)
+            result.site.description = textOrThrow(site.description, 'Site description');
+    }
+    if (body.theme !== undefined) {
+        const theme = (body.theme && typeof body.theme === 'object' ? body.theme : {});
+        result.theme = {};
+        for (const [key, value] of Object.entries(theme)) {
+            if (!THEME_FIELDS.includes(key))
+                throw new DoxloopError(`"${key}" is not a branding field.`, 2);
+            if (value === null || value === '') {
+                result.theme[key] = null;
+                continue;
+            }
+            result.theme[key] = validateField(key, textOrThrow(value, key));
+        }
+    }
+    return result;
+}
+function validateField(field, value) {
+    const trimmed = value.trim();
+    if (THEME_COLOR_FIELDS.includes(field)) {
+        const color = trimmed.toLowerCase();
+        if (!/^#[0-9a-f]{6}$/.test(color))
+            throw new DoxloopError(`${label(field)} must be a six-digit hex colour such as #6366f1.`, 2);
+        return color;
+    }
+    if (THEME_FONT_FIELDS.includes(field)) {
+        if (!trimmed || trimmed.length > 80 || /[<>"';{}]/.test(trimmed))
+            throw new DoxloopError(`${label(field)} must be a font family name.`, 2);
+        return trimmed;
+    }
+    if (field === 'mode') {
+        if (!THEME_MODES.includes(trimmed))
+            throw new DoxloopError('Colour mode must be light, dark, or system.', 2);
+        return trimmed;
+    }
+    if (field === 'codeTheme') {
+        if (!THEME_CODE_THEMES.includes(trimmed))
+            throw new DoxloopError('Code theme must be auto, light, or dark.', 2);
+        return trimmed;
+    }
+    if (!/^(?:https:\/\/|\/(?!\/))/i.test(trimmed) || /\s/.test(trimmed)) {
+        throw new DoxloopError(`${label(field)} must be an HTTPS address or a root-relative path such as /assets/logo.svg.`, 2);
+    }
+    if (trimmed.startsWith('/') && trimmed.split('/').some((part) => part === '..')) {
+        throw new DoxloopError(`${label(field)} cannot leave the documentation folder.`, 2);
+    }
+    return trimmed;
+}
+function describeChange(input, project) {
+    const fields = Object.keys(input.theme ?? {});
+    const site = Object.keys(input.site ?? {});
+    const parts = [...site.map((key) => `site ${key}`), ...fields.map(label)];
+    return parts.length > 0 ? `Updated branding: ${parts.join(', ')}` : `Updated branding for ${project.title}`;
+}
+function label(field) {
+    const words = {
+        primaryColor: 'Primary colour',
+        lightColor: 'Light-mode accent',
+        darkColor: 'Dark-mode accent',
+        backgroundColorLight: 'Light background',
+        backgroundColorDark: 'Dark background',
+        font: 'Body font',
+        headingFont: 'Heading font',
+        codeFont: 'Code font',
+        logoLight: 'Light logo',
+        logoDark: 'Dark logo',
+        favicon: 'Favicon',
+        faviconLight: 'Light favicon',
+        faviconDark: 'Dark favicon',
+        backgroundImage: 'Background image',
+        logoHref: 'Logo link',
+        mode: 'Colour mode',
+        codeTheme: 'Code theme',
+    };
+    return words[field] ?? field;
+}
+function textOrThrow(value, name) {
+    if (typeof value !== 'string')
+        throw new DoxloopError(`${name} must be text.`, 2);
+    if (value.length > 500)
+        throw new DoxloopError(`${name} is too long.`, 2);
+    return value;
+}
+function themeObject(value) {
+    if (typeof value === 'string')
+        return { mode: value };
+    if (value && typeof value === 'object' && !Array.isArray(value))
+        return { ...value };
+    return {};
+}
+function fingerprint(text) {
+    return createHash('sha256').update(text).digest('hex');
+}
+//# sourceMappingURL=branding.js.map

package/dist/bundle-upload.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Doxbrix runs on Vercel, which rejects function request bodies over 4.5 MB
+ * before the API sees them (a bare `413 FUNCTION_PAYLOAD_TOO_LARGE`). Bundles
+ * above this threshold are uploaded straight to storage through presigned URLs
+ * and committed by `uploadId`; smaller ones stay a single request, which every
+ * Doxbrix version accepts.
+ */
+export declare const INLINE_BUNDLE_LIMIT_BYTES: number;
+export interface PushableBundle {
+    manifest: unknown;
+    basePath: string;
+    pages: Array<{
+        path: string;
+        markdown: string;
+    }>;
+    media: Array<{
+        path: string;
+        base64: string;
+    }>;
+    verification?: unknown;
+}
+export declare function pushDeploymentBundle<T>(slug: string, bundle: PushableBundle, options: {
+    publish: boolean;
+    replace: boolean;
+}, apiUrl?: string): Promise<T>;
+//# sourceMappingURL=bundle-upload.d.ts.map

package/dist/bundle-upload.js

@@ -0,0 +1,99 @@
+import { createHash } from 'node:crypto';
+import { authenticatedRequest, authenticatedRequestOptional } from './auth.js';
+import { DoxloopError } from './errors.js';
+/**
+ * Doxbrix runs on Vercel, which rejects function request bodies over 4.5 MB
+ * before the API sees them (a bare `413 FUNCTION_PAYLOAD_TOO_LARGE`). Bundles
+ * above this threshold are uploaded straight to storage through presigned URLs
+ * and committed by `uploadId`; smaller ones stay a single request, which every
+ * Doxbrix version accepts.
+ */
+export const INLINE_BUNDLE_LIMIT_BYTES = 3.5 * 1024 * 1024;
+const PLATFORM_BODY_LIMIT_BYTES = 4.5 * 1024 * 1024;
+const UPLOAD_CONCURRENCY = 4;
+const UPLOAD_ATTEMPTS = 3;
+export async function pushDeploymentBundle(slug, bundle, options, apiUrl) {
+    const path = `/api/v1/projects/${encodeURIComponent(slug)}/bundle`;
+    const inline = JSON.stringify({ ...bundle, ...options });
+    const inlineBytes = Buffer.byteLength(inline);
+    const postInline = () => authenticatedRequest(path, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: inline }, apiUrl);
+    if (inlineBytes <= INLINE_BUNDLE_LIMIT_BYTES)
+        return postInline();
+    const media = bundle.media.map((file) => {
+        const data = Buffer.from(file.base64, 'base64');
+        return { path: file.path, data, sha256: sha256Hex(data) };
+    });
+    const staged = Buffer.from(JSON.stringify({
+        manifest: bundle.manifest,
+        basePath: bundle.basePath,
+        pages: bundle.pages,
+        ...(bundle.verification === undefined ? {} : { verification: bundle.verification }),
+        mediaRefs: media.map(({ path: mediaPath, sha256 }) => ({ path: mediaPath, sha256 })),
+    }));
+    const reservation = await authenticatedRequestOptional(`${path}/uploads`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            bundle: { bytes: staged.length, sha256: sha256Hex(staged) },
+            media: media.map(({ path: mediaPath, data, sha256 }) => ({ path: mediaPath, bytes: data.length, sha256 })),
+        }),
+    }, apiUrl);
+    if (!reservation) {
+        // This Doxbrix predates staged uploads, so the single request is all it takes.
+        if (inlineBytes > PLATFORM_BODY_LIMIT_BYTES) {
+            throw new DoxloopError(`This deployment is ${formatMiB(inlineBytes)}, but this Doxbrix server accepts at most 4.5 MB in one deployment. Update Doxbrix, or reduce the size of images in the documentation.`);
+        }
+        return postInline();
+    }
+    if (!reservation.uploadId || !reservation.bundle) {
+        throw new DoxloopError('Doxbrix did not return an upload location for the deployment bundle.');
+    }
+    const dataByPath = new Map(media.map((file) => [file.path, file.data]));
+    const uploads = reservation.media.flatMap((file) => file.status === 'upload' ? [{ upload: file.upload, data: dataByPath.get(file.path), label: file.path }] : []);
+    let next = 0;
+    const worker = async () => {
+        while (next < uploads.length) {
+            const item = uploads[next++];
+            await putPresigned(item.upload, item.data, item.label);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(UPLOAD_CONCURRENCY, uploads.length) }, () => worker()));
+    await putPresigned(reservation.bundle.upload, staged, 'deployment bundle');
+    return authenticatedRequest(path, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ uploadId: reservation.uploadId, ...options }),
+    }, apiUrl);
+}
+/** PUT bytes to a presigned storage URL. The Doxbrix token is never sent here. */
+async function putPresigned(upload, data, label) {
+    let failure = '';
+    for (let attempt = 1; attempt <= UPLOAD_ATTEMPTS; attempt++) {
+        if (attempt > 1)
+            await new Promise((resolve) => setTimeout(resolve, 500 * 2 ** (attempt - 2)));
+        try {
+            const response = await fetch(upload.url, {
+                method: upload.method,
+                headers: upload.headers,
+                body: data,
+                redirect: 'error',
+            });
+            if (response.ok)
+                return;
+            failure = `${response.status} ${response.statusText}`.trim();
+            if (response.status < 500)
+                break;
+        }
+        catch (error) {
+            failure = error instanceof Error ? error.message : String(error);
+        }
+    }
+    throw new DoxloopError(`Upload of ${label} failed: ${failure}`);
+}
+function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+function formatMiB(bytes) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+//# sourceMappingURL=bundle-upload.js.map

package/dist/capture-auth.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Sign-in material for the screenshot capture browser.
+ *
+ * Applications that need a signed-in user can be documented in two ways:
+ * a recorded browser session (cookies and local storage saved after the user
+ * signs in by hand in a visible Chrome window) or saved credentials the agent
+ * types into the sign-in form through the capture server's secret store.
+ * Neither is written into the project: both live under the user's Doxloop
+ * config home, keyed by the project root, with owner-only permissions.
+ */
+export declare const CAPTURE_USERNAME_SECRET = "DOXLOOP_APP_USERNAME";
+export declare const CAPTURE_PASSWORD_SECRET = "DOXLOOP_APP_PASSWORD";
+export interface StorageStateCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/** The Playwright storage-state shape the capture server reads back. */
+export interface CaptureStorageState {
+    cookies: StorageStateCookie[];
+    origins: Array<{
+        origin: string;
+        localStorage: Array<{
+            name: string;
+            value: string;
+        }>;
+    }>;
+}
+export interface CaptureCredentials {
+    username: string;
+    password: string;
+}
+export interface StoredCaptureSession {
+    savedAt: string;
+    origin: string;
+    state: CaptureStorageState;
+}
+export interface CaptureAuthStatus {
+    credentials?: {
+        username: string;
+        savedAt: string;
+    };
+    session?: {
+        savedAt: string;
+        origin: string;
+        cookies: number;
+        origins: number;
+    };
+}
+/** What the readiness check and prompts need to know, without the secrets. */
+export interface CaptureAuthContext {
+    session?: CaptureStorageState;
+    credentials: boolean;
+}
+export interface CaptureAuthMaterial {
+    /** Playwright storage-state file passed to the capture server, when a session is saved. */
+    storageStatePath?: string;
+    /** dotenv secrets file passed to the capture server, when credentials are saved. */
+    secretsPath?: string;
+    /** Delete the per-run secrets file. The storage state stays for the next run. */
+    cleanup(): Promise<void>;
+}
+interface StoredCredentials extends CaptureCredentials {
+    savedAt: string;
+}
+export declare function captureAuthDirectory(root: string): string;
+export declare function saveCaptureCredentials(root: string, credentials: CaptureCredentials): Promise<void>;
+export declare function removeCaptureCredentials(root: string): Promise<void>;
+export declare function loadCaptureCredentials(root: string): Promise<StoredCredentials | undefined>;
+export declare function saveCaptureSession(root: string, origin: string, state: CaptureStorageState): Promise<StoredCaptureSession>;
+export declare function removeCaptureSession(root: string): Promise<void>;
+export declare function loadCaptureSession(root: string): Promise<StoredCaptureSession | undefined>;
+export declare function captureAuthStatus(root: string): Promise<CaptureAuthStatus>;
+export declare function captureAuthContext(root: string): Promise<CaptureAuthContext>;
+/**
+ * Materialize the saved sign-in for one capture run. The storage state is
+ * rewritten from the stored session so the file the browser reads is always
+ * the plain Playwright shape; the secrets file exists only while the run does.
+ */
+export declare function prepareCaptureAuth(root: string): Promise<CaptureAuthMaterial | undefined>;
+/**
+ * The readiness probe is a plain HTTP request, so it carries the session
+ * cookies the browser would send for the URL: matching domain, matching path
+ * prefix, not expired, and not secure-only on a plain HTTP page.
+ */
+export declare function sessionCookieHeader(state: CaptureStorageState | undefined, url: string): string | undefined;
+export type CaptureAuthMode = 'none' | 'session' | 'credentials' | 'both';
+export declare function describeCaptureAuth(context: CaptureAuthContext | CaptureAuthStatus | undefined): CaptureAuthMode;
+export {};
+//# sourceMappingURL=capture-auth.d.ts.map

package/dist/capture-auth.js

@@ -0,0 +1,204 @@
+import { createHash } from 'node:crypto';
+import { chmod, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { DoxloopError } from './errors.js';
+import { pathExists } from './fs.js';
+/**
+ * Sign-in material for the screenshot capture browser.
+ *
+ * Applications that need a signed-in user can be documented in two ways:
+ * a recorded browser session (cookies and local storage saved after the user
+ * signs in by hand in a visible Chrome window) or saved credentials the agent
+ * types into the sign-in form through the capture server's secret store.
+ * Neither is written into the project: both live under the user's Doxloop
+ * config home, keyed by the project root, with owner-only permissions.
+ */
+export const CAPTURE_USERNAME_SECRET = 'DOXLOOP_APP_USERNAME';
+export const CAPTURE_PASSWORD_SECRET = 'DOXLOOP_APP_PASSWORD';
+export function captureAuthDirectory(root) {
+    const key = createHash('sha256').update(resolve(root)).digest('hex').slice(0, 20);
+    const home = process.env.DOXLOOP_CONFIG_HOME ?? join(homedir(), '.config', 'doxloop');
+    return join(home, 'capture-auth', key);
+}
+export async function saveCaptureCredentials(root, credentials) {
+    const username = credentials.username.trim();
+    const password = credentials.password;
+    if (!username)
+        throw new DoxloopError('Enter the sign-in username or email.');
+    if (!password)
+        throw new DoxloopError('Enter the sign-in password.');
+    if (/[\r\n]/.test(username))
+        throw new DoxloopError('The sign-in username cannot span lines.');
+    const stored = { username, password, savedAt: new Date().toISOString() };
+    await writePrivateFile(join(captureAuthDirectory(root), 'credentials.json'), JSON.stringify(stored, null, 2));
+}
+export async function removeCaptureCredentials(root) {
+    await rm(join(captureAuthDirectory(root), 'credentials.json'), { force: true });
+}
+export async function loadCaptureCredentials(root) {
+    const parsed = await readPrivateJson(join(captureAuthDirectory(root), 'credentials.json'));
+    if (!parsed || typeof parsed.username !== 'string' || typeof parsed.password !== 'string')
+        return undefined;
+    return { username: parsed.username, password: parsed.password, savedAt: typeof parsed.savedAt === 'string' ? parsed.savedAt : '' };
+}
+export async function saveCaptureSession(root, origin, state) {
+    if (!isStorageState(state))
+        throw new DoxloopError('The browser did not return a usable session.');
+    if (state.cookies.length === 0 && state.origins.every((item) => item.localStorage.length === 0)) {
+        throw new DoxloopError('The browser session holds no cookies or local storage yet. Complete the sign-in in the Chrome window before saving.');
+    }
+    const stored = { savedAt: new Date().toISOString(), origin, state };
+    await writePrivateFile(join(captureAuthDirectory(root), 'session.json'), JSON.stringify(stored, null, 2));
+    return stored;
+}
+export async function removeCaptureSession(root) {
+    const directory = captureAuthDirectory(root);
+    await Promise.all([
+        rm(join(directory, 'session.json'), { force: true }),
+        rm(join(directory, 'storage-state.json'), { force: true }),
+    ]);
+}
+export async function loadCaptureSession(root) {
+    const parsed = await readPrivateJson(join(captureAuthDirectory(root), 'session.json'));
+    if (!parsed || !isStorageState(parsed.state))
+        return undefined;
+    return {
+        savedAt: typeof parsed.savedAt === 'string' ? parsed.savedAt : '',
+        origin: typeof parsed.origin === 'string' ? parsed.origin : '',
+        state: parsed.state,
+    };
+}
+export async function captureAuthStatus(root) {
+    const [credentials, session] = await Promise.all([loadCaptureCredentials(root), loadCaptureSession(root)]);
+    return {
+        ...(credentials ? { credentials: { username: credentials.username, savedAt: credentials.savedAt } } : {}),
+        ...(session ? { session: { savedAt: session.savedAt, origin: session.origin, cookies: session.state.cookies.length, origins: session.state.origins.length } } : {}),
+    };
+}
+export async function captureAuthContext(root) {
+    const [credentials, session] = await Promise.all([loadCaptureCredentials(root), loadCaptureSession(root)]);
+    return { ...(session ? { session: session.state } : {}), credentials: Boolean(credentials) };
+}
+/**
+ * Materialize the saved sign-in for one capture run. The storage state is
+ * rewritten from the stored session so the file the browser reads is always
+ * the plain Playwright shape; the secrets file exists only while the run does.
+ */
+export async function prepareCaptureAuth(root) {
+    const [credentials, session] = await Promise.all([loadCaptureCredentials(root), loadCaptureSession(root)]);
+    if (!credentials && !session)
+        return undefined;
+    const directory = captureAuthDirectory(root);
+    const material = { cleanup: async () => { } };
+    if (session) {
+        const path = join(directory, 'storage-state.json');
+        await writePrivateFile(path, JSON.stringify(session.state));
+        material.storageStatePath = path;
+    }
+    if (credentials) {
+        await removeStaleSecretsFiles(directory);
+        const path = join(directory, `secrets-${process.pid}-${Date.now()}.env`);
+        await writePrivateFile(path, `${CAPTURE_USERNAME_SECRET}=${dotenvValue(credentials.username)}\n${CAPTURE_PASSWORD_SECRET}=${dotenvValue(credentials.password)}\n`);
+        material.secretsPath = path;
+        material.cleanup = () => rm(path, { force: true });
+    }
+    return material;
+}
+/**
+ * A run that is killed never reaches its cleanup, so its secrets file would
+ * outlive it. Files named for a process that no longer exists are removed
+ * before a new one is written; a live run's file is left alone.
+ */
+async function removeStaleSecretsFiles(directory) {
+    let entries;
+    try {
+        entries = await readdir(directory);
+    }
+    catch {
+        return;
+    }
+    await Promise.all(entries.map(async (entry) => {
+        const match = /^secrets-(\d+)-\d+\.env$/.exec(entry);
+        if (!match)
+            return;
+        const pid = Number(match[1]);
+        if (pid === process.pid || processAlive(pid))
+            return;
+        await rm(join(directory, entry), { force: true });
+    }));
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but belongs to someone else.
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * The readiness probe is a plain HTTP request, so it carries the session
+ * cookies the browser would send for the URL: matching domain, matching path
+ * prefix, not expired, and not secure-only on a plain HTTP page.
+ */
+export function sessionCookieHeader(state, url) {
+    if (!state)
+        return undefined;
+    const target = new URL(url);
+    const now = Date.now() / 1000;
+    const pairs = state.cookies
+        .filter((cookie) => cookieMatchesHost(cookie.domain, target.hostname))
+        .filter((cookie) => target.pathname.startsWith(cookie.path || '/'))
+        .filter((cookie) => cookie.expires === undefined || cookie.expires < 0 || cookie.expires > now)
+        .filter((cookie) => !cookie.secure || target.protocol === 'https:' || target.hostname === 'localhost' || target.hostname === '127.0.0.1')
+        .map((cookie) => `${cookie.name}=${cookie.value}`);
+    return pairs.length > 0 ? pairs.join('; ') : undefined;
+}
+export function describeCaptureAuth(context) {
+    if (!context)
+        return 'none';
+    const session = Boolean(context.session);
+    const credentials = 'credentials' in context && Boolean(context.credentials);
+    if (session && credentials)
+        return 'both';
+    if (session)
+        return 'session';
+    if (credentials)
+        return 'credentials';
+    return 'none';
+}
+function cookieMatchesHost(domain, hostname) {
+    const normalized = domain.startsWith('.') ? domain.slice(1) : domain;
+    return hostname === normalized || hostname.endsWith(`.${normalized}`);
+}
+function dotenvValue(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r')}"`;
+}
+function isStorageState(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const state = value;
+    return Array.isArray(state.cookies) && Array.isArray(state.origins);
+}
+async function writePrivateFile(path, content) {
+    const directory = join(path, '..');
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await writeFile(path, `${content}\n`, { encoding: 'utf8', mode: 0o600 });
+    if (process.platform !== 'win32') {
+        await chmod(directory, 0o700);
+        await chmod(path, 0o600);
+    }
+}
+async function readPrivateJson(path) {
+    if (!(await pathExists(path)))
+        return undefined;
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        throw new DoxloopError(`Cannot read the saved capture sign-in at ${path}. Remove the file and save it again.`);
+    }
+}
+//# sourceMappingURL=capture-auth.js.map