@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/agents.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { constants } from 'node:fs';
 import { access, cp, lstat, mkdir, readFile, readdir, rm, stat, } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { delimiter, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import spawn from 'cross-spawn';
@@ -9,6 +10,23 @@ import { pathExists } from './fs.js';
 import { loadGeneratorAdapter } from './generators.js';
 import { loadProject } from './project.js';
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export const AGENT_CATALOG = [
+    {
+        name: 'codex',
+        displayName: 'Codex',
+        packageName: '@openai/codex',
+    },
+    {
+        name: 'claude',
+        displayName: 'Claude Code',
+        packageName: '@anthropic-ai/claude-code',
+    },
+    {
+        name: 'gemini',
+        displayName: 'Gemini',
+        packageName: '@google/gemini-cli',
+    },
+];
 export function parseAgent(value) {
     if (value === undefined)
         return undefined;
@@ -102,15 +120,56 @@ function skillDestinationsFor(root, skillName, agent) {
 }
 export async function detectAgents() {
     const found = [];
-    for (const name of ['codex', 'claude', 'gemini']) {
-        const executable = await findExecutable(name);
+    for (const agent of AGENT_CATALOG) {
+        const executable = await findExecutable(agent.name);
         if (executable)
-            found.push({ name, executable });
+            found.push({ name: agent.name, executable });
     }
     return found;
 }
+export async function installAgent(name, options = {}) {
+    const agent = AGENT_CATALOG.find((candidate) => candidate.name === name);
+    if (!agent)
+        throw new DoxloopError(`Unsupported agent: ${name}`);
+    const npm = await findExecutable('npm');
+    if (!npm) {
+        throw new DoxloopError(`Cannot install ${agent.displayName} because npm is not available on PATH. Install npm, then run \`npm install --global ${agent.packageName}\`.`, 2);
+    }
+    const exitCode = await new Promise((resolveInstall, rejectInstall) => {
+        const child = spawn(npm, ['install', '--global', agent.packageName], {
+            stdio: options.onOutput ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+            env: process.env,
+        });
+        options.onChild?.(child);
+        if (options.onOutput) {
+            child.stdout?.on('data', (chunk) => options.onOutput?.(chunk.toString()));
+            child.stderr?.on('data', (chunk) => options.onOutput?.(chunk.toString()));
+        }
+        child.once('error', (error) => {
+            rejectInstall(new DoxloopError(`Could not start npm to install ${agent.displayName}: ${error.message}`, 2));
+        });
+        child.once('exit', (code, signal) => {
+            if (signal) {
+                rejectInstall(new DoxloopError(`${agent.displayName} installation was stopped by ${signal}.`, 2));
+            }
+            else {
+                resolveInstall(code ?? 1);
+            }
+        });
+    });
+    if (exitCode !== 0) {
+        throw new DoxloopError(`Could not install ${agent.displayName} (npm exited with code ${exitCode}). Retry with \`npm install --global ${agent.packageName}\`.`, 2);
+    }
+    const executable = await findExecutable(name);
+    if (!executable) {
+        throw new DoxloopError(`${agent.displayName} was installed, but \`${name}\` is not available on PATH. Open a new terminal and run Doxloop again.`, 2);
+    }
+    return { name, executable };
+}
 export async function chooseAgent(preferred) {
-    const candidates = preferred ? [preferred] : ['codex', 'claude', 'gemini'];
+    const candidates = preferred
+        ? [preferred]
+        : AGENT_CATALOG.map((agent) => agent.name);
     for (const name of candidates) {
         const executable = await findExecutable(name);
         if (executable)
@@ -119,13 +178,9 @@ export async function chooseAgent(preferred) {
     const expected = preferred ?? 'Codex, Claude Code, or Gemini';
     throw new DoxloopError(`${expected} is not available on PATH. Install an agent or use --print to copy the prompt.`);
 }
-export async function agentAuthenticationStatus(agent) {
-    if (agent.name === 'gemini') {
-        return {
-            status: 'unknown',
-            detail: 'Gemini authentication cannot be verified automatically; it will be checked when Gemini starts.',
-        };
-    }
+export async function agentAuthenticationStatus(agent, options = {}) {
+    if (agent.name === 'gemini')
+        return geminiAuthenticationStatus(options);
     const args = agent.name === 'codex'
         ? ['login', 'status']
         : ['auth', 'status', '--json'];
@@ -166,6 +221,37 @@ export async function agentAuthenticationStatus(agent) {
             : 'Claude Code is not signed in. Run `claude auth login`.',
     };
 }
+/**
+ * Gemini CLI has no non-interactive status command, so its sign-in is read
+ * from the places it keeps credentials: an API key or Vertex AI project in
+ * the environment, or the OAuth token file a Google sign-in leaves behind.
+ * Only presence is checked; no credential value is read into memory for
+ * longer than the parse, and none is reported.
+ */
+export async function geminiAuthenticationStatus(options = {}) {
+    const env = options.env ?? process.env;
+    if (env.GEMINI_API_KEY?.trim() || env.GOOGLE_API_KEY?.trim()) {
+        return { status: 'authenticated', detail: 'Gemini uses the API key from the environment.' };
+    }
+    const vertex = env.GOOGLE_GENAI_USE_VERTEXAI?.trim().toLowerCase();
+    if ((vertex === 'true' || vertex === '1') && (env.GOOGLE_CLOUD_PROJECT?.trim() || env.GOOGLE_APPLICATION_CREDENTIALS?.trim())) {
+        return { status: 'authenticated', detail: 'Gemini uses Vertex AI credentials from the environment.' };
+    }
+    const credentials = join(options.home ?? homedir(), '.gemini', 'oauth_creds.json');
+    try {
+        const parsed = JSON.parse(await readFile(credentials, 'utf8'));
+        if (typeof parsed.refresh_token === 'string' || typeof parsed.access_token === 'string') {
+            return { status: 'authenticated', detail: 'Gemini is signed in with a Google account.' };
+        }
+    }
+    catch {
+        // No token file, or one Gemini itself would not accept.
+    }
+    return {
+        status: 'unauthenticated',
+        detail: 'Gemini is not signed in. Run `gemini` once in a terminal and complete the sign-in, or set GEMINI_API_KEY.',
+    };
+}
 async function runAgentStatus(executable, args) {
     return new Promise((resolveStatus) => {
         const child = spawn(executable, args, {
@@ -194,6 +280,24 @@ async function runAgentStatus(executable, args) {
     });
 }
 async function findExecutable(name) {
+    if (name === 'codex' || name === 'claude' || name === 'gemini') {
+        const override = process.env[`DOXLOOP_AGENT_EXECUTABLE_${name.toUpperCase()}`];
+        if (override) {
+            const candidate = resolve(override);
+            try {
+                const stats = await stat(candidate);
+                if (stats.isFile()) {
+                    if (process.platform !== 'win32')
+                        await access(candidate, constants.X_OK);
+                    return candidate;
+                }
+                throw new Error('not a file');
+            }
+            catch {
+                throw new DoxloopError(`The test agent executable for ${name} is not runnable: ${candidate}`);
+            }
+        }
+    }
     const path = process.env.PATH;
     if (!path)
         return undefined;

package/dist/api-coverage.d.ts

@@ -0,0 +1,11 @@
+import type { ValidationIssue } from './types.js';
+/** `METHOD /path` for every `<ApiEndpoint>` block in a page. */
+export declare function documentedOperations(content: string): string[];
+/**
+ * One warning per contract operation that no page documents with an
+ * `<ApiEndpoint>` block, filed against the page that mentions it (the
+ * operation itself first, then its path). Operations no page mentions are
+ * returned without a file so the caller can report them without a fix session.
+ */
+export declare function contractCoverageIssues(root: string, files: string[]): Promise<ValidationIssue[]>;
+//# sourceMappingURL=api-coverage.d.ts.map

package/dist/api-coverage.js

@@ -0,0 +1,72 @@
+/**
+ * API contract coverage for Doxbrix sites.
+ *
+ * A RealWorld run documented 14 of the contract's 19 operations with an
+ * `<ApiEndpoint>` block; login, registration, article deletion, and the two
+ * favorite operations were written as curl walkthroughs on how-to pages, so
+ * the published reference had no "Try it" entry for them and nothing flagged
+ * the gap. The end-of-run check now names each contract operation without a
+ * reference block and hands it to the page that already talks about it.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { discoverDocumentationSources } from './source-discovery.js';
+const ENDPOINT_TAG = /<ApiEndpoint\b([^>]*)>/g;
+/** `METHOD /path` for every `<ApiEndpoint>` block in a page. */
+export function documentedOperations(content) {
+    const found = [];
+    for (const match of content.matchAll(ENDPOINT_TAG)) {
+        const method = /\bmethod=["']([A-Za-z]+)["']/.exec(match[1])?.[1];
+        const path = /\bpath=["']([^"']+)["']/.exec(match[1])?.[1];
+        if (method && path)
+            found.push(`${method.toUpperCase()} ${normalizePath(path)}`);
+    }
+    return found;
+}
+/**
+ * One warning per contract operation that no page documents with an
+ * `<ApiEndpoint>` block, filed against the page that mentions it (the
+ * operation itself first, then its path). Operations no page mentions are
+ * returned without a file so the caller can report them without a fix session.
+ */
+export async function contractCoverageIssues(root, files) {
+    let operations;
+    try {
+        const { inventory } = await discoverDocumentationSources(root);
+        operations = [...new Set(inventory.sources.flatMap((source) => source.evidence.filter((row) => row.contract && row.kind === 'operation').map((row) => row.label)))];
+    }
+    catch {
+        return [];
+    }
+    if (operations.length === 0)
+        return [];
+    const pages = [];
+    for (const file of files) {
+        try {
+            pages.push({ file, content: await readFile(join(root, file), 'utf8') });
+        }
+        catch { /* A page the run did not write. */ }
+    }
+    const documented = new Set(pages.flatMap((page) => documentedOperations(page.content)));
+    const issues = [];
+    for (const operation of operations) {
+        const [method = '', ...rest] = operation.split(' ');
+        const path = normalizePath(rest.join(' '));
+        if (documented.has(`${method} ${path}`))
+            continue;
+        const mentions = (page) => page.content.includes(`${method} ${rest.join(' ')}`) || page.content.includes(`${method} ${path}`);
+        const home = pages.find(mentions) ?? pages.find((page) => page.content.includes(rest.join(' ')));
+        issues.push({
+            severity: 'warning',
+            code: 'api-endpoint-missing',
+            message: `The API contract's ${operation} has no <ApiEndpoint> reference block on any page. Add one on this page where it discusses the operation: method, path, baseUrl, a <Param> for each path, query, header, and body field, and a <Response> for the success and each documented error status, all taken from the contract.`,
+            ...(home ? { file: home.file } : {}),
+        });
+    }
+    return issues;
+}
+/** `{slug}` and `:slug` path parameters compare equal. */
+function normalizePath(path) {
+    return path.trim().replace(/:([A-Za-z_][\w]*)/g, '{$1}').replace(/\/+$/, '') || '/';
+}
+//# sourceMappingURL=api-coverage.js.map

package/dist/application-probe.d.ts

@@ -0,0 +1,28 @@
+/** Paths (or hash routes) a product uses for its sign-in screen. */
+export declare const SIGN_IN_ROUTE: RegExp;
+export interface SignInProbeObservation {
+    /** Where the page ended up once client routing settled. */
+    finalUrl: string;
+    /** Whether a visible password field is on the page. */
+    hasPasswordField: boolean;
+}
+export interface SignInWall {
+    /** The sign-in route the visitor was sent to, such as `/auth` or `/_/#/login`. */
+    signInPath: string;
+}
+/**
+ * Decide from what the browser saw whether the page is a sign-in wall: the
+ * final route looks like a sign-in route, or a password field is visible.
+ */
+export declare function signInWallFromObservation(observation: SignInProbeObservation): SignInWall | undefined;
+export type SignInProbe = (url: string, options?: {
+    timeoutMs?: number;
+}) => Promise<SignInWall | undefined>;
+/**
+ * Load `url` headless and report a sign-in wall, or undefined when the page
+ * is not one or nothing could be learned (no browser, timeout, crash).
+ */
+export declare function probeSignInWall(url: string, options?: {
+    timeoutMs?: number;
+}): Promise<SignInWall | undefined>;
+//# sourceMappingURL=application-probe.d.ts.map

package/dist/application-probe.js

@@ -0,0 +1,93 @@
+/**
+ * A single-page application answers every route with HTTP 200 and decides in
+ * the browser whether the visitor may stay, so a plain fetch reports a sign-in
+ * wall as a reachable page. This probe loads the page in the managed headless
+ * browser, lets client routing settle, and reports where the visitor landed.
+ * It never throws: a missing browser or a slow page means "no evidence".
+ */
+import { loadInstalledPlaywright } from './capture.js';
+/** Paths (or hash routes) a product uses for its sign-in screen. */
+export const SIGN_IN_ROUTE = /(?:^|[/#])(?:login|log-in|signin|sign-in|sign_in|auth|authenticate|sso|oauth)(?:[/?#]|$)/i;
+/**
+ * Decide from what the browser saw whether the page is a sign-in wall: the
+ * final route looks like a sign-in route, or a password field is visible.
+ */
+export function signInWallFromObservation(observation) {
+    let url;
+    try {
+        url = new URL(observation.finalUrl);
+    }
+    catch {
+        return observation.hasPasswordField ? { signInPath: observation.finalUrl } : undefined;
+    }
+    const hash = url.hash && url.hash !== '#' ? url.hash.replace(/\?.*$/, '') : '';
+    if (SIGN_IN_ROUTE.test(url.pathname))
+        return { signInPath: url.pathname };
+    // Hash-routed applications (PocketBase `/_/#/login`) keep the route after `#`.
+    if (hash && SIGN_IN_ROUTE.test(hash))
+        return { signInPath: `${url.pathname}${hash}` };
+    if (observation.hasPasswordField)
+        return { signInPath: `${url.pathname}${hash}` };
+    return undefined;
+}
+const DEFAULT_PROBE_TIMEOUT_MS = 8_000;
+/** Client-side guards often redirect just after the first idle moment. */
+const SETTLE_AFTER_IDLE_MS = 400;
+/**
+ * Load `url` headless and report a sign-in wall, or undefined when the page
+ * is not one or nothing could be learned (no browser, timeout, crash).
+ */
+export async function probeSignInWall(url, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    let browser;
+    let timer;
+    let abandoned = false;
+    const run = async () => {
+        const playwright = await loadInstalledPlaywright();
+        if (!playwright || abandoned)
+            return undefined;
+        const launched = (await playwright.chromium.launch({ headless: true }));
+        // The overall deadline may have passed while the browser started.
+        if (abandoned) {
+            await launched.close().catch(() => { });
+            return undefined;
+        }
+        browser = launched;
+        const context = await browser.newContext({ viewport: { width: 1280, height: 800 } });
+        const page = (await context.newPage());
+        const deadline = Date.now() + timeoutMs;
+        await page.goto(url, { waitUntil: 'domcontentloaded', timeout: timeoutMs });
+        await page.waitForLoadState('networkidle', { timeout: Math.max(500, deadline - Date.now()) }).catch(() => { });
+        await page.waitForTimeout(Math.min(SETTLE_AFTER_IDLE_MS, Math.max(0, deadline - Date.now())));
+        let hasPasswordField = false;
+        try {
+            const field = page.locator('input[type="password"]');
+            hasPasswordField = (await field.count()) > 0 && (await field.first().isVisible());
+        }
+        catch {
+            hasPasswordField = false;
+        }
+        return signInWallFromObservation({ finalUrl: page.url(), hasPasswordField });
+    };
+    try {
+        return await Promise.race([
+            run().catch(() => undefined),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(undefined), timeoutMs + 4_000);
+                timer.unref?.();
+            }),
+        ]);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        abandoned = true;
+        if (timer)
+            clearTimeout(timer);
+        const opened = browser;
+        if (opened)
+            await opened.close().catch(() => { });
+    }
+}
+//# sourceMappingURL=application-probe.js.map

package/dist/application-url.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolve an application route (`/settings`) against the configured base URL.
+ *
+ * Plain `new URL(route, base)` is wrong for a hash-routed single-page
+ * application (`https://host/_/#`): the route lives in the fragment, so
+ * `/settings` must open `https://host/_/#/settings`, not `https://host/settings`
+ * (which the server answers with 404). Every other base URL keeps the standard
+ * resolution, because some projects configure a page such as `/login` as the
+ * base and still write routes from the origin root.
+ */
+export declare function applicationUrl(baseUrl: string, route: string | undefined): URL;
+/** A base URL ending in an empty or route-shaped fragment (`#`, `#/`) is hash-routed. */
+export declare function hashRouted(base: URL | string): boolean;
+//# sourceMappingURL=application-url.d.ts.map

package/dist/application-url.js

@@ -0,0 +1,26 @@
+/**
+ * Resolve an application route (`/settings`) against the configured base URL.
+ *
+ * Plain `new URL(route, base)` is wrong for a hash-routed single-page
+ * application (`https://host/_/#`): the route lives in the fragment, so
+ * `/settings` must open `https://host/_/#/settings`, not `https://host/settings`
+ * (which the server answers with 404). Every other base URL keeps the standard
+ * resolution, because some projects configure a page such as `/login` as the
+ * base and still write routes from the origin root.
+ */
+export function applicationUrl(baseUrl, route) {
+    const base = new URL(baseUrl);
+    const path = route?.trim() || '/';
+    if (!hashRouted(base) || /^[a-z][a-z0-9+.-]*:/i.test(path) || path.startsWith('//'))
+        return new URL(path, base);
+    const document = new URL(base.toString());
+    const routed = path.startsWith('#') ? path.slice(1) : path;
+    document.hash = routed.startsWith('/') ? routed : `/${routed}`;
+    return document;
+}
+/** A base URL ending in an empty or route-shaped fragment (`#`, `#/`) is hash-routed. */
+export function hashRouted(base) {
+    const url = typeof base === 'string' ? new URL(base) : base;
+    return url.href.includes('#') && (url.hash === '' || url.hash.startsWith('#/'));
+}
+//# sourceMappingURL=application-url.js.map

package/dist/args.js

@@ -1,16 +1,31 @@
 import { UsageError } from './errors.js';
 const BOOLEAN_FLAGS = new Set([
+    'backfill-evidence',
+    'ignore-screenshot-problems',
     'dry-run',
     'h',
     'help',
     'open',
     'print',
     'public',
+    'quiet',
     'screenshots',
     'no-screenshots',
+    'no-open',
     'v',
     'version',
     'yes',
+    'offline',
+    'rendered',
+    'examples',
+    'fix',
+    'update-visuals',
+    'warnings-as-errors',
+    'approve-baseline',
+    'approve-quality-baseline',
+    'allow-related',
+    'existing',
+    'zip',
 ]);
 export function parseArgs(argv) {
     const flags = new Map();

package/dist/artifact-deploy.d.ts

@@ -6,4 +6,13 @@ export declare function deployGeneratedSite(options: {
     public?: boolean;
     apiUrl?: string;
 }): Promise<void>;
+export declare function containedOutput(root: string, outputDir: string): string;
+export declare function runLocalBuild(generator: string, command: string, root: string, siteUrl: string): Promise<void>;
+export declare function packageStaticOutput(root: string): Promise<{
+    archive: Uint8Array;
+    files: number;
+    omittedSourceMaps: number;
+    sha256: string;
+}>;
+export declare function writeDryRunArchive(root: string, archive: Uint8Array): Promise<string>;
 //# sourceMappingURL=artifact-deploy.d.ts.map

package/dist/artifact-deploy.js

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { lstat, readdir, readFile } from 'node:fs/promises';
-import { basename, extname, relative, resolve, sep } from 'node:path';
+import { lstat, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, extname, join, relative, resolve, sep } from 'node:path';
 import { zipSync } from 'fflate';
 import { apiUrl, authenticatedRequest, authenticatedRequestOptional } from './auth.js';
 import { DoxloopError } from './errors.js';
@@ -65,7 +65,8 @@ export async function deployGeneratedSite(options) {
         const packaged = await packageStaticOutput(outputRoot);
         building.done(`Built ${adapter.displayName} artifact`, `${packaged.files} files, ${formatBytes(packaged.archive.byteLength)}${packaged.omittedSourceMaps ? `, omitted ${packaged.omittedSourceMaps} source maps` : ''}`);
         if (options.dryRun) {
-            process.stdout.write(`\nDeployment is valid.\nGenerator: ${project.generator}\nVisibility: ${visibility}\nOutput: ${adapter.build.outputDir}\nFiles: ${packaged.files}\nArtifact: ${formatBytes(packaged.archive.byteLength)}\nSHA-256: ${packaged.sha256}\nNo data was uploaded.\n`);
+            const archivePath = await writeDryRunArchive(options.root, packaged.archive);
+            process.stdout.write(`\nDeployment is valid.\nGenerator: ${project.generator}\nVisibility: ${visibility}\nOutput: ${adapter.build.outputDir}\nFiles: ${packaged.files}\nArtifact: ${formatBytes(packaged.archive.byteLength)}\nArchive: ${archivePath}\nSHA-256: ${packaged.sha256}\nNo data was uploaded.\n`);
             return;
         }
         if (!target)
@@ -104,7 +105,7 @@ function assertArtifactProject(project, generator) {
         throw new DoxloopError(`Project "${project.slug}" expects generator "${project.generator ?? 'unknown'}", but this Doxloop project uses "${generator}". Choose another --slug.`);
     }
 }
-function containedOutput(root, outputDir) {
+export function containedOutput(root, outputDir) {
     const base = resolve(root);
     const output = resolve(base, outputDir);
     if (output === base || !output.startsWith(`${base}${sep}`)) {
@@ -112,10 +113,14 @@ function containedOutput(root, outputDir) {
     }
     return output;
 }
-async function runLocalBuild(generator, command, root, siteUrl) {
+export async function runLocalBuild(generator, command, root, siteUrl) {
     const environment = { ...process.env, DOXLOOP_SITE_URL: siteUrl, SITE_URL: siteUrl };
     delete environment.DOXLOOP_TOKEN;
     delete environment.DOXBRIX_TOKEN;
+    delete environment.DOXLOOP_NETLIFY_TOKEN;
+    delete environment.NETLIFY_AUTH_TOKEN;
+    delete environment.DOXLOOP_VERCEL_TOKEN;
+    delete environment.VERCEL_TOKEN;
     const effectiveCommand = generator === 'hugo'
         ? `${command} --baseURL ${JSON.stringify(`${siteUrl.replace(/\/$/, '')}/`)}`
         : generator === 'jekyll'
@@ -135,7 +140,7 @@ async function runLocalBuild(generator, command, root, siteUrl) {
         throw new DoxloopError(`Local generator build failed (exit ${code}). Doxloop does not install dependencies during deploy; install them and run \`${command}\` locally to diagnose.`);
     }
 }
-async function packageStaticOutput(root) {
+export async function packageStaticOutput(root) {
     let rootStat;
     try {
         rootStat = await lstat(root);
@@ -181,9 +186,16 @@ async function packageStaticOutput(root) {
             if (/-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/.test(text)) {
                 throw new DoxloopError(`Build output appears to contain a private key: ${path}`);
             }
-            const activeTokens = [process.env.DOXLOOP_TOKEN, process.env.DOXBRIX_TOKEN].filter((value) => Boolean(value && value.length >= 12));
+            const activeTokens = [
+                process.env.DOXLOOP_TOKEN,
+                process.env.DOXBRIX_TOKEN,
+                process.env.DOXLOOP_NETLIFY_TOKEN,
+                process.env.NETLIFY_AUTH_TOKEN,
+                process.env.DOXLOOP_VERCEL_TOKEN,
+                process.env.VERCEL_TOKEN,
+            ].filter((value) => Boolean(value && value.length >= 12));
             if (activeTokens.some((token) => text.includes(token)) || /\bdxb_[A-Za-z0-9_-]{20,}\b/.test(text)) {
-                throw new DoxloopError(`Build output appears to contain a Doxbrix access token: ${path}`);
+                throw new DoxloopError(`Build output appears to contain a deployment access token: ${path}`);
             }
             entries[path] = new Uint8Array(data);
             if (path === 'index.html')
@@ -200,6 +212,14 @@ async function packageStaticOutput(root) {
         throw new DoxloopError(`Compressed artifact exceeds ${formatBytes(MAX_ZIP_BYTES)}.`);
     return { archive, files, omittedSourceMaps, sha256: createHash('sha256').update(archive).digest('hex') };
 }
+export async function writeDryRunArchive(root, archive) {
+    const directory = join(root, '.doxloop', 'exports');
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const path = join(directory, `${stamp}.zip`);
+    await writeFile(path, archive, { mode: 0o600 });
+    return path;
+}
 function assertSafeArtifactName(path) {
     const name = basename(path).toLowerCase();
     if (name === '.env' || name.startsWith('.env.') || name === 'id_rsa' || name === 'id_ed25519' ||

package/dist/assets.d.ts

@@ -0,0 +1,72 @@
+import type { GeneratorAdapter } from './generator-api.js';
+import type { DoxloopProject } from './types.js';
+/**
+ * Images and downloadable files that documentation pages reference. Uploads
+ * land in the generator's conventional asset directory and are referenced by
+ * a public path pages can use directly; the library lists every asset with the
+ * pages that embed it so alt text can be edited and unused files deleted.
+ */
+export declare const ASSET_IMAGE_EXTENSIONS: Set<string>;
+export declare const ASSET_FILE_EXTENSIONS: Set<string>;
+export declare const MAX_ASSET_BYTES: number;
+export interface AssetReference {
+    page: string;
+    alt: string;
+}
+export interface AssetEntry {
+    /** Project-relative path. */
+    path: string;
+    name: string;
+    /** The address a page uses to embed the asset. */
+    publicPath: string;
+    kind: 'image' | 'file';
+    bytes: number;
+    modifiedAt: string;
+    references: AssetReference[];
+}
+export interface AssetLibrary {
+    /** Project-relative directory uploads go to. */
+    directory: string;
+    publicPrefix: string;
+    maxBytes: number;
+    assets: AssetEntry[];
+}
+export declare function assetLocation(project: DoxloopProject, adapter?: GeneratorAdapter): {
+    directory: string;
+    publicPrefix: string;
+};
+export declare function readAssetLibrary(root: string): Promise<AssetLibrary>;
+export declare function listAssets(root: string, loaded?: DoxloopProject, loadedAdapter?: GeneratorAdapter): Promise<AssetEntry[]>;
+export interface AssetUpload {
+    name: string;
+    /** Base64 file content, with or without a data-URL prefix. */
+    data: string;
+    /** Project-relative directory inside the content or asset folder; defaults to the generator's asset directory. */
+    directory?: string;
+    /** Overwrite an existing file with the same name. */
+    replace?: boolean;
+}
+export declare function uploadAsset(root: string, raw: unknown): Promise<AssetEntry>;
+export declare function deleteAsset(root: string, raw: unknown): Promise<{
+    removed: string;
+}>;
+/** Rewrite the alt text of every reference to one asset across the pages that embed it. */
+export declare function updateAssetAlt(root: string, raw: unknown): Promise<AssetEntry>;
+/** Replace one screenshot in a proposal workspace before the proposal is accepted. */
+export declare function replaceRunCapture(root: string, raw: unknown): Promise<{
+    run: string;
+    path: string;
+    bytes: number;
+}>;
+/**
+ * Markdown image references and HTML `img`/`source` tags with their alt text.
+ * Exposed so the page service and the library agree on what counts as a
+ * reference.
+ */
+export declare function pageAssetReferences(raw: string): Array<{
+    reference: string;
+    alt: string;
+}>;
+export declare function safeAssetName(raw: string): string;
+export declare function decodeUpload(data: string, name: string): Buffer;
+//# sourceMappingURL=assets.d.ts.map